<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Threads</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="index.html" title="GLib Reference Manual">
<link rel="up" href="glib-core.html" title="GLib Core Application Support">
<link rel="prev" href="glib-The-Main-Event-Loop.html" title="The Main Event Loop">
<link rel="next" href="glib-Thread-Pools.html" title="Thread Pools">
<meta name="generator" content="GTK-Doc V1.17 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="glib-The-Main-Event-Loop.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="glib-core.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GLib Reference Manual</th>
<td><a accesskey="n" href="glib-Thread-Pools.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts">
<a href="#glib-Threads.synopsis" class="shortcut">Top</a>
                   | 
                  <a href="#glib-Threads.description" class="shortcut">Description</a>
</td></tr>
</table>
<div class="refentry">
<a name="glib-Threads"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="glib-Threads.top_of_page"></a>Threads</span></h2>
<p>Threads — thread abstraction; including threads, different
                    mutexes, conditions and thread private data</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<a name="glib-Threads.synopsis"></a><h2>Synopsis</h2>
<pre class="synopsis">
#include &lt;glib.h&gt;

#define             <a class="link" href="glib-Threads.html#G-THREADS-ENABLED:CAPS" title="G_THREADS_ENABLED">G_THREADS_ENABLED</a>
#define             <a class="link" href="glib-Threads.html#G-THREADS-IMPL-POSIX:CAPS" title="G_THREADS_IMPL_POSIX">G_THREADS_IMPL_POSIX</a>
#define             <a class="link" href="glib-Threads.html#G-THREADS-IMPL-NONE:CAPS" title="G_THREADS_IMPL_NONE">G_THREADS_IMPL_NONE</a>

#define             <a class="link" href="glib-Threads.html#G-THREAD-ERROR:CAPS" title="G_THREAD_ERROR">G_THREAD_ERROR</a>
enum                <a class="link" href="glib-Threads.html#GThreadError" title="enum GThreadError">GThreadError</a>;

struct              <a class="link" href="glib-Threads.html#GThreadFunctions" title="struct GThreadFunctions">GThreadFunctions</a>;
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()">g_thread_init</a>                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GThreadFunctions" title="struct GThreadFunctions"><span class="type">GThreadFunctions</span></a> *vtable</code></em>);
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-thread-supported" title="g_thread_supported ()">g_thread_supported</a>                  ();
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-thread-get-initialized" title="g_thread_get_initialized ()">g_thread_get_initialized</a>            (<em class="parameter"><code><span class="type">void</span></code></em>);

<a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            (<a class="link" href="glib-Threads.html#GThreadFunc" title="GThreadFunc ()">*GThreadFunc</a>)                      (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);
enum                <a class="link" href="glib-Threads.html#GThreadPriority" title="enum GThreadPriority">GThreadPriority</a>;
struct              <a class="link" href="glib-Threads.html#GThread" title="struct GThread">GThread</a>;
<a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="returnvalue">GThread</span></a> *           <a class="link" href="glib-Threads.html#g-thread-create" title="g_thread_create ()">g_thread_create</a>                     (<em class="parameter"><code><a class="link" href="glib-Threads.html#GThreadFunc" title="GThreadFunc ()"><span class="type">GThreadFunc</span></a> func</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> joinable</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);
<a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="returnvalue">GThread</span></a> *           <a class="link" href="glib-Threads.html#g-thread-create-full" title="g_thread_create_full ()">g_thread_create_full</a>                (<em class="parameter"><code><a class="link" href="glib-Threads.html#GThreadFunc" title="GThreadFunc ()"><span class="type">GThreadFunc</span></a> func</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a> stack_size</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> joinable</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> bound</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GThreadPriority" title="enum GThreadPriority"><span class="type">GThreadPriority</span></a> priority</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);
<a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="returnvalue">GThread</span></a> *           <a class="link" href="glib-Threads.html#g-thread-self" title="g_thread_self ()">g_thread_self</a>                       (<em class="parameter"><code><span class="type">void</span></code></em>);
<a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()">g_thread_join</a>                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="type">GThread</span></a> *thread</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-thread-set-priority" title="g_thread_set_priority ()">g_thread_set_priority</a>               (<em class="parameter"><code><a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="type">GThread</span></a> *thread</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GThreadPriority" title="enum GThreadPriority"><span class="type">GThreadPriority</span></a> priority</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-thread-yield" title="g_thread_yield ()">g_thread_yield</a>                      ();
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-thread-exit" title="g_thread_exit ()">g_thread_exit</a>                       (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> retval</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-thread-foreach" title="g_thread_foreach ()">g_thread_foreach</a>                    (<em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GFunc" title="GFunc ()"><span class="type">GFunc</span></a> thread_func</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);

                    <a class="link" href="glib-Threads.html#GMutex" title="GMutex">GMutex</a>;
<a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="returnvalue">GMutex</span></a> *            <a class="link" href="glib-Threads.html#g-mutex-new" title="g_mutex_new ()">g_mutex_new</a>                         ();
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-mutex-lock" title="g_mutex_lock ()">g_mutex_lock</a>                        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-mutex-trylock" title="g_mutex_trylock ()">g_mutex_trylock</a>                     (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-mutex-unlock" title="g_mutex_unlock ()">g_mutex_unlock</a>                      (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-mutex-free" title="g_mutex_free ()">g_mutex_free</a>                        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);

                    <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex">GStaticMutex</a>;
#define             <a class="link" href="glib-Threads.html#G-STATIC-MUTEX-INIT:CAPS" title="G_STATIC_MUTEX_INIT">G_STATIC_MUTEX_INIT</a>
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-mutex-init" title="g_static_mutex_init ()">g_static_mutex_init</a>                 (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> *mutex</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-mutex-lock" title="g_static_mutex_lock ()">g_static_mutex_lock</a>                 (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> *mutex</code></em>);
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-static-mutex-trylock" title="g_static_mutex_trylock ()">g_static_mutex_trylock</a>              (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> *mutex</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-mutex-unlock" title="g_static_mutex_unlock ()">g_static_mutex_unlock</a>               (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> *mutex</code></em>);
<a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="returnvalue">GMutex</span></a> *            <a class="link" href="glib-Threads.html#g-static-mutex-get-mutex" title="g_static_mutex_get_mutex ()">g_static_mutex_get_mutex</a>            (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> *mutex</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-mutex-free" title="g_static_mutex_free ()">g_static_mutex_free</a>                 (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> *mutex</code></em>);

#define             <a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()">G_LOCK_DEFINE</a>                       (name)
#define             <a class="link" href="glib-Threads.html#G-LOCK-DEFINE-STATIC:CAPS" title="G_LOCK_DEFINE_STATIC()">G_LOCK_DEFINE_STATIC</a>                (name)
#define             <a class="link" href="glib-Threads.html#G-LOCK-EXTERN:CAPS" title="G_LOCK_EXTERN()">G_LOCK_EXTERN</a>                       (name)
#define             <a class="link" href="glib-Threads.html#G-LOCK:CAPS" title="G_LOCK()">G_LOCK</a>                              (name)
#define             <a class="link" href="glib-Threads.html#G-TRYLOCK:CAPS" title="G_TRYLOCK()">G_TRYLOCK</a>                           (name)
#define             <a class="link" href="glib-Threads.html#G-UNLOCK:CAPS" title="G_UNLOCK()">G_UNLOCK</a>                            (name)

struct              <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex">GStaticRecMutex</a>;
#define             <a class="link" href="glib-Threads.html#G-STATIC-REC-MUTEX-INIT:CAPS" title="G_STATIC_REC_MUTEX_INIT">G_STATIC_REC_MUTEX_INIT</a>
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-rec-mutex-init" title="g_static_rec_mutex_init ()">g_static_rec_mutex_init</a>             (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> *mutex</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-rec-mutex-lock" title="g_static_rec_mutex_lock ()">g_static_rec_mutex_lock</a>             (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> *mutex</code></em>);
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-static-rec-mutex-trylock" title="g_static_rec_mutex_trylock ()">g_static_rec_mutex_trylock</a>          (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> *mutex</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-rec-mutex-unlock" title="g_static_rec_mutex_unlock ()">g_static_rec_mutex_unlock</a>           (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> *mutex</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-rec-mutex-lock-full" title="g_static_rec_mutex_lock_full ()">g_static_rec_mutex_lock_full</a>        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> *mutex</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> depth</code></em>);
<a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               <a class="link" href="glib-Threads.html#g-static-rec-mutex-unlock-full" title="g_static_rec_mutex_unlock_full ()">g_static_rec_mutex_unlock_full</a>      (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> *mutex</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-rec-mutex-free" title="g_static_rec_mutex_free ()">g_static_rec_mutex_free</a>             (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> *mutex</code></em>);

struct              <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock">GStaticRWLock</a>;
#define             <a class="link" href="glib-Threads.html#G-STATIC-RW-LOCK-INIT:CAPS" title="G_STATIC_RW_LOCK_INIT">G_STATIC_RW_LOCK_INIT</a>
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-rw-lock-init" title="g_static_rw_lock_init ()">g_static_rw_lock_init</a>               (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> *lock</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-rw-lock-reader-lock" title="g_static_rw_lock_reader_lock ()">g_static_rw_lock_reader_lock</a>        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> *lock</code></em>);
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-static-rw-lock-reader-trylock" title="g_static_rw_lock_reader_trylock ()">g_static_rw_lock_reader_trylock</a>     (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> *lock</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-rw-lock-reader-unlock" title="g_static_rw_lock_reader_unlock ()">g_static_rw_lock_reader_unlock</a>      (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> *lock</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-rw-lock-writer-lock" title="g_static_rw_lock_writer_lock ()">g_static_rw_lock_writer_lock</a>        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> *lock</code></em>);
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-static-rw-lock-writer-trylock" title="g_static_rw_lock_writer_trylock ()">g_static_rw_lock_writer_trylock</a>     (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> *lock</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-rw-lock-writer-unlock" title="g_static_rw_lock_writer_unlock ()">g_static_rw_lock_writer_unlock</a>      (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> *lock</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-rw-lock-free" title="g_static_rw_lock_free ()">g_static_rw_lock_free</a>               (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> *lock</code></em>);

                    <a class="link" href="glib-Threads.html#GCond" title="GCond">GCond</a>;
<a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="returnvalue">GCond</span></a>*              <a class="link" href="glib-Threads.html#g-cond-new" title="g_cond_new ()">g_cond_new</a>                          ();
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-cond-signal" title="g_cond_signal ()">g_cond_signal</a>                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a> *cond</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-cond-broadcast" title="g_cond_broadcast ()">g_cond_broadcast</a>                    (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a> *cond</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-cond-wait" title="g_cond_wait ()">g_cond_wait</a>                         (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a> *cond</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-cond-timed-wait" title="g_cond_timed_wait ()">g_cond_timed_wait</a>                   (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a> *cond</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> *mutex</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Date-and-Time-Functions.html#GTimeVal" title="struct GTimeVal"><span class="type">GTimeVal</span></a> *abs_time</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-cond-free" title="g_cond_free ()">g_cond_free</a>                         (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a> *cond</code></em>);

                    <a class="link" href="glib-Threads.html#GPrivate" title="GPrivate">GPrivate</a>;
<a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="returnvalue">GPrivate</span></a>*           <a class="link" href="glib-Threads.html#g-private-new" title="g_private_new ()">g_private_new</a>                       (<em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> destructor</code></em>);
<a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Threads.html#g-private-get" title="g_private_get ()">g_private_get</a>                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="type">GPrivate</span></a> *private_key</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-private-set" title="g_private_set ()">g_private_set</a>                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="type">GPrivate</span></a> *private_key</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);

struct              <a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate">GStaticPrivate</a>;
#define             <a class="link" href="glib-Threads.html#G-STATIC-PRIVATE-INIT:CAPS" title="G_STATIC_PRIVATE_INIT">G_STATIC_PRIVATE_INIT</a>
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-private-init" title="g_static_private_init ()">g_static_private_init</a>               (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a> *private_key</code></em>);
<a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Threads.html#g-static-private-get" title="g_static_private_get ()">g_static_private_get</a>                (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a> *private_key</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-private-set" title="g_static_private_set ()">g_static_private_set</a>                (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a> *private_key</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> notify</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-static-private-free" title="g_static_private_free ()">g_static_private_free</a>               (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a> *private_key</code></em>);

struct              <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce">GOnce</a>;
enum                <a class="link" href="glib-Threads.html#GOnceStatus" title="enum GOnceStatus">GOnceStatus</a>;
#define             <a class="link" href="glib-Threads.html#G-ONCE-INIT:CAPS" title="G_ONCE_INIT">G_ONCE_INIT</a>
#define             <a class="link" href="glib-Threads.html#g-once" title="g_once()">g_once</a>                              (once,
                                                         func,
                                                         arg)
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-once-init-enter" title="g_once_init_enter ()">g_once_init_enter</a>                   (<em class="parameter"><code>volatile <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *value_location</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-once-init-leave" title="g_once_init_leave ()">g_once_init_leave</a>                   (<em class="parameter"><code>volatile <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *value_location</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> initialization_value</code></em>);

<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-bit-lock" title="g_bit_lock ()">g_bit_lock</a>                          (<em class="parameter"><code>volatile <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-bit-trylock" title="g_bit_trylock ()">g_bit_trylock</a>                       (<em class="parameter"><code>volatile <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-bit-unlock" title="g_bit_unlock ()">g_bit_unlock</a>                        (<em class="parameter"><code>volatile <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);
</pre>
</div>
<div class="refsect1">
<a name="glib-Threads.description"></a><h2>Description</h2>
<p>
Threads act almost like processes, but unlike processes all threads
of one process share the same memory. This is good, as it provides
easy communication between the involved threads via this shared
memory, and it is bad, because strange things (so called
"Heisenbugs") might happen if the program is not carefully designed.
In particular, due to the concurrent nature of threads, no
assumptions on the order of execution of code running in different
threads can be made, unless order is explicitly forced by the
programmer through synchronization primitives.
</p>
<p>
The aim of the thread related functions in GLib is to provide a
portable means for writing multi-threaded software. There are
primitives for mutexes to protect the access to portions of memory
(<a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a>, <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>, <a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a>, <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> and
<a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a>). There is a facility to use individual bits for
locks (<a class="link" href="glib-Threads.html#g-bit-lock" title="g_bit_lock ()"><code class="function">g_bit_lock()</code></a>). There are primitives for condition variables to
allow synchronization of threads (<a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a>).  There are primitives for
thread-private data - data that every thread has a private instance
of (<a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="type">GPrivate</span></a>, <a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a>). There are facilities for one-time
initialization (<a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a>, <a class="link" href="glib-Threads.html#g-once-init-enter" title="g_once_init_enter ()"><code class="function">g_once_init_enter()</code></a>). Last but definitely
not least there are primitives to portably create and manage
threads (<a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="type">GThread</span></a>).
</p>
<p>
The threading system is initialized with <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a>, which
takes an optional custom thread implementation or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> for the
default implementation. If you want to call <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> with a
non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> argument this must be done before executing any other GLib
functions (except <a class="link" href="glib-Memory-Allocation.html#g-mem-set-vtable" title="g_mem_set_vtable ()"><code class="function">g_mem_set_vtable()</code></a>). This is a requirement even if
no threads are in fact ever created by the process.
</p>
<p>
Calling <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> with a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> argument is somewhat more
relaxed. You may call any other glib functions in the main thread
before <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> as long as <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> is not called from
a glib callback, or with any locks held. However, many libraries
above glib does not support late initialization of threads, so doing
this should be avoided if possible.
</p>
<p>
Please note that since version 2.24 the GObject initialization
function <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#g-type-init"><code class="function">g_type_init()</code></a> initializes threads (with a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> argument),
so most applications, including those using Gtk+ will run with
threads enabled. If you want a special thread implementation, make
sure you call <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> before <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#g-type-init"><code class="function">g_type_init()</code></a> is called.
</p>
<p>
After calling <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a>, GLib is completely thread safe (all
global data is automatically locked), but individual data structure
instances are not automatically locked for performance reasons. So,
for example you must coordinate accesses to the same <a class="link" href="glib-Hash-Tables.html#GHashTable" title="GHashTable"><span class="type">GHashTable</span></a>
from multiple threads.  The two notable exceptions from this rule
are <a class="link" href="glib-The-Main-Event-Loop.html#GMainLoop" title="GMainLoop"><span class="type">GMainLoop</span></a> and <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>, which <span class="emphasis"><em>are</em></span>
threadsafe and need no further application-level locking to be
accessed from multiple threads.
</p>
<p>
To help debugging problems in multithreaded applications, GLib
supports error-checking mutexes that will give you helpful error
messages on common problems. To use error-checking mutexes, define
the symbol <span class="type">G_ERRORCHECK_MUTEXES</span> when compiling the application.
</p>
</div>
<div class="refsect1">
<a name="glib-Threads.details"></a><h2>Details</h2>
<div class="refsect2">
<a name="G-THREADS-ENABLED:CAPS"></a><h3>G_THREADS_ENABLED</h3>
<pre class="programlisting">#define G_THREADS_ENABLED
</pre>
<p>
This macro is defined if GLib was compiled with thread support. This
does not necessarily mean that there is a thread implementation
available, but it does mean that the infrastructure is in place and
that once you provide a thread implementation to <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a>,
GLib will be multi-thread safe. If <a class="link" href="glib-Threads.html#G-THREADS-ENABLED:CAPS" title="G_THREADS_ENABLED"><span class="type">G_THREADS_ENABLED</span></a> is not
defined, then Glib is not, and cannot be, multi-thread safe.
</p>
</div>
<hr>
<div class="refsect2">
<a name="G-THREADS-IMPL-POSIX:CAPS"></a><h3>G_THREADS_IMPL_POSIX</h3>
<pre class="programlisting">#define G_THREADS_IMPL_POSIX
</pre>
<p>
This macro is defined if POSIX style threads are used.
</p>
</div>
<hr>
<div class="refsect2">
<a name="G-THREADS-IMPL-NONE:CAPS"></a><h3>G_THREADS_IMPL_NONE</h3>
<pre class="programlisting">#define G_THREADS_IMPL_NONE
</pre>
<p>
This macro is defined if no thread implementation is used. You can,
however, provide one to <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> to make GLib multi-thread
safe.
</p>
</div>
<hr>
<div class="refsect2">
<a name="G-THREAD-ERROR:CAPS"></a><h3>G_THREAD_ERROR</h3>
<pre class="programlisting">#define G_THREAD_ERROR g_thread_error_quark ()
</pre>
<p>
The error domain of the GLib thread subsystem.
</p>
</div>
<hr>
<div class="refsect2">
<a name="GThreadError"></a><h3>enum GThreadError</h3>
<pre class="programlisting">typedef enum
{
  G_THREAD_ERROR_AGAIN /* Resource temporarily unavailable */
} GThreadError;
</pre>
<p>
Possible errors of thread related functions.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><a name="G-THREAD-ERROR-AGAIN:CAPS"></a><span class="term"><code class="literal">G_THREAD_ERROR_AGAIN</code></span></p></td>
<td>a thread couldn't be created due to resource
                       shortage. Try again later.
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="GThreadFunctions"></a><h3>struct GThreadFunctions</h3>
<pre class="programlisting">struct GThreadFunctions {
  GMutex*  (*mutex_new)           (void);
  void     (*mutex_lock)          (GMutex               *mutex);
  gboolean (*mutex_trylock)       (GMutex               *mutex);
  void     (*mutex_unlock)        (GMutex               *mutex);
  void     (*mutex_free)          (GMutex               *mutex);
  GCond*   (*cond_new)            (void);
  void     (*cond_signal)         (GCond                *cond);
  void     (*cond_broadcast)      (GCond                *cond);
  void     (*cond_wait)           (GCond                *cond,
                                   GMutex               *mutex);
  gboolean (*cond_timed_wait)     (GCond                *cond,
                                   GMutex               *mutex,
                                   GTimeVal             *end_time);
  void      (*cond_free)          (GCond                *cond);
  GPrivate* (*private_new)        (GDestroyNotify        destructor);
  gpointer  (*private_get)        (GPrivate             *private_key);
  void      (*private_set)        (GPrivate             *private_key,
                                   gpointer              data);
  void      (*thread_create)      (GThreadFunc           func,
                                   gpointer              data,
                                   gulong                stack_size,
                                   gboolean              joinable,
                                   gboolean              bound,
                                   GThreadPriority       priority,
                                   gpointer              thread,
                                   GError              **error);
  void      (*thread_yield)       (void);
  void      (*thread_join)        (gpointer              thread);
  void      (*thread_exit)        (void);
  void      (*thread_set_priority)(gpointer              thread,
                                   GThreadPriority       priority);
  void      (*thread_self)        (gpointer              thread);
  gboolean  (*thread_equal)       (gpointer              thread1,
				   gpointer              thread2);
};
</pre>
<p>
This function table is used by <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> to initialize the
thread system. The functions in the table are directly used by their
g_* prepended counterparts (described in this document).  For
example, if you call <a class="link" href="glib-Threads.html#g-mutex-new" title="g_mutex_new ()"><code class="function">g_mutex_new()</code></a> then <code class="function">mutex_new()</code> from the table
provided to <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> will be called.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Do not use this struct unless you know what you are
doing.</p>
</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.mutex-new"></a>mutex_new</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-mutex-new" title="g_mutex_new ()"><code class="function">g_mutex_new()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.mutex-lock"></a>mutex_lock</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-mutex-lock" title="g_mutex_lock ()"><code class="function">g_mutex_lock()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.mutex-trylock"></a>mutex_trylock</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-mutex-trylock" title="g_mutex_trylock ()"><code class="function">g_mutex_trylock()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.mutex-unlock"></a>mutex_unlock</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-mutex-unlock" title="g_mutex_unlock ()"><code class="function">g_mutex_unlock()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.mutex-free"></a>mutex_free</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-mutex-free" title="g_mutex_free ()"><code class="function">g_mutex_free()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.cond-new"></a>cond_new</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-cond-new" title="g_cond_new ()"><code class="function">g_cond_new()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.cond-signal"></a>cond_signal</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-cond-signal" title="g_cond_signal ()"><code class="function">g_cond_signal()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.cond-broadcast"></a>cond_broadcast</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-cond-broadcast" title="g_cond_broadcast ()"><code class="function">g_cond_broadcast()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.cond-wait"></a>cond_wait</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-cond-wait" title="g_cond_wait ()"><code class="function">g_cond_wait()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.cond-timed-wait"></a>cond_timed_wait</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-cond-timed-wait" title="g_cond_timed_wait ()"><code class="function">g_cond_timed_wait()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.cond-free"></a>cond_free</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-cond-free" title="g_cond_free ()"><code class="function">g_cond_free()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.private-new"></a>private_new</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-private-new" title="g_private_new ()"><code class="function">g_private_new()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.private-get"></a>private_get</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-private-get" title="g_private_get ()"><code class="function">g_private_get()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.private-set"></a>private_set</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-private-set" title="g_private_set ()"><code class="function">g_private_set()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.thread-create"></a>thread_create</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-thread-create" title="g_thread_create ()"><code class="function">g_thread_create()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.thread-yield"></a>thread_yield</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-thread-yield" title="g_thread_yield ()"><code class="function">g_thread_yield()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.thread-join"></a>thread_join</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.thread-exit"></a>thread_exit</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-thread-exit" title="g_thread_exit ()"><code class="function">g_thread_exit()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.thread-set-priority"></a>thread_set_priority</code></em> ()</span></p></td>
<td>virtual function pointer for
<a class="link" href="glib-Threads.html#g-thread-set-priority" title="g_thread_set_priority ()"><code class="function">g_thread_set_priority()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.thread-self"></a>thread_self</code></em> ()</span></p></td>
<td>virtual function pointer for <a class="link" href="glib-Threads.html#g-thread-self" title="g_thread_self ()"><code class="function">g_thread_self()</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GThreadFunctions.thread-equal"></a>thread_equal</code></em> ()</span></p></td>
<td>used internally by recursive mutex locks and by some
assertion checks</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-init"></a><h3>g_thread_init ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_thread_init                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GThreadFunctions" title="struct GThreadFunctions"><span class="type">GThreadFunctions</span></a> *vtable</code></em>);</pre>
<p>
If you use GLib from more than one thread, you must initialize the
thread system by calling <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a>. Most of the time you will
only have to call <code class="literal">g_thread_init (NULL)</code>.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Do not call <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> with a non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> parameter unless
you really know what you are doing.</p>
</div>
<p>
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p><a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> must not be called directly or indirectly as a
callback from GLib. Also no mutexes may be currently locked while
calling <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a>.</p>
</div>
<p>
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p><a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> changes the way in which <a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="type">GTimer</span></a> measures
elapsed time. As a consequence, timers that are running while
<a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> is called may report unreliable times.</p>
</div>
<p>
</p>
<p>
Calling <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> multiple times is allowed (since version
2.24), but nothing happens except for the first call. If the
argument is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> on such a call a warning will be printed, but
otherwise the argument is ignored.
</p>
<p>
If no thread system is available and <em class="parameter"><code>vtable</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> or if not all
elements of <em class="parameter"><code>vtable</code></em> are non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, then <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> will abort.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>To use <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> in your program, you have to link with
the libraries that the command <span class="command"><strong>pkg-config --libs
gthread-2.0</strong></span> outputs. This is not the case for all the
other thread related functions of GLib. Those can be used without
having to link with the thread libraries.</p>
</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>vtable</code></em> :</span></p></td>
<td>a function table of type <a class="link" href="glib-Threads.html#GThreadFunctions" title="struct GThreadFunctions"><span class="type">GThreadFunctions</span></a>, that provides
the entry points to the thread system to be used.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-supported"></a><h3>g_thread_supported ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_thread_supported                  ();</pre>
<p>
This function returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the thread system is initialized, and
<a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> if it is not.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>This function is actually a macro. Apart from taking the
address of it you can however use it as if it was a
function.</p>
</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, if the thread system is initialized.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-get-initialized"></a><h3>g_thread_get_initialized ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_thread_get_initialized            (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
<p>
Indicates if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has been called.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if threads have been initialized.</td>
</tr></tbody>
</table></div>
<p class="since">Since 2.20</p>
</div>
<hr>
<div class="refsect2">
<a name="GThreadFunc"></a><h3>GThreadFunc ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            (*GThreadFunc)                      (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
<p>
Specifies the type of the <em class="parameter"><code>func</code></em> functions passed to
<a class="link" href="glib-Threads.html#g-thread-create" title="g_thread_create ()"><code class="function">g_thread_create()</code></a> or <a class="link" href="glib-Threads.html#g-thread-create-full" title="g_thread_create_full ()"><code class="function">g_thread_create_full()</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
<td>data passed to the thread.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>the return value of the thread, which will be returned by
<a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a>.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="GThreadPriority"></a><h3>enum GThreadPriority</h3>
<pre class="programlisting">typedef enum
{
  G_THREAD_PRIORITY_LOW,
  G_THREAD_PRIORITY_NORMAL,
  G_THREAD_PRIORITY_HIGH,
  G_THREAD_PRIORITY_URGENT
} GThreadPriority;
</pre>
<p>
Specifies the priority of a thread.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>It is not guaranteed that threads with different priorities
really behave accordingly. On some systems (e.g. Linux) there are no
thread priorities. On other systems (e.g. Solaris) there doesn't
seem to be different scheduling for different priorities. All in all
try to avoid being dependent on priorities.</p>
</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><a name="G-THREAD-PRIORITY-LOW:CAPS"></a><span class="term"><code class="literal">G_THREAD_PRIORITY_LOW</code></span></p></td>
<td>a priority lower than normal
</td>
</tr>
<tr>
<td><p><a name="G-THREAD-PRIORITY-NORMAL:CAPS"></a><span class="term"><code class="literal">G_THREAD_PRIORITY_NORMAL</code></span></p></td>
<td>the default priority
</td>
</tr>
<tr>
<td><p><a name="G-THREAD-PRIORITY-HIGH:CAPS"></a><span class="term"><code class="literal">G_THREAD_PRIORITY_HIGH</code></span></p></td>
<td>a priority higher than normal
</td>
</tr>
<tr>
<td><p><a name="G-THREAD-PRIORITY-URGENT:CAPS"></a><span class="term"><code class="literal">G_THREAD_PRIORITY_URGENT</code></span></p></td>
<td>the highest priority
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="GThread"></a><h3>struct GThread</h3>
<pre class="programlisting">struct GThread {
};
</pre>
<p>
The <a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="type">GThread</span></a> struct represents a running thread. It has three public
read-only members, but the underlying struct is bigger, so you must
not copy this struct.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Resources for a joinable thread are not fully released
until <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a> is called for that thread.</p>
</div>
<p>
</p>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-create"></a><h3>g_thread_create ()</h3>
<pre class="programlisting"><a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="returnvalue">GThread</span></a> *           g_thread_create                     (<em class="parameter"><code><a class="link" href="glib-Threads.html#GThreadFunc" title="GThreadFunc ()"><span class="type">GThreadFunc</span></a> func</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> joinable</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);</pre>
<p>
This function creates a new thread with the default priority.
</p>
<p>
If <em class="parameter"><code>joinable</code></em> is <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, you can wait for this threads termination
calling <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a>. Otherwise the thread will just disappear
when it terminates.
</p>
<p>
The new thread executes the function <em class="parameter"><code>func</code></em> with the argument <em class="parameter"><code>data</code></em>.
If the thread was created successfully, it is returned.
</p>
<p>
<em class="parameter"><code>error</code></em> can be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore errors, or non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to report errors.
The error is set, if and only if the function returns <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
<td>a function to execute in the new thread.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
<td>an argument to supply to the new thread.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>joinable</code></em> :</span></p></td>
<td>should this thread be joinable?</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
<td>return location for error.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>the new <a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="type">GThread</span></a> on success.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-create-full"></a><h3>g_thread_create_full ()</h3>
<pre class="programlisting"><a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="returnvalue">GThread</span></a> *           g_thread_create_full                (<em class="parameter"><code><a class="link" href="glib-Threads.html#GThreadFunc" title="GThreadFunc ()"><span class="type">GThreadFunc</span></a> func</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a> stack_size</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> joinable</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> bound</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GThreadPriority" title="enum GThreadPriority"><span class="type">GThreadPriority</span></a> priority</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);</pre>
<p>
This function creates a new thread with the priority <em class="parameter"><code>priority</code></em>. If
the underlying thread implementation supports it, the thread gets a
stack size of <em class="parameter"><code>stack_size</code></em> or the default value for the current
platform, if <em class="parameter"><code>stack_size</code></em> is 0.
</p>
<p>
If <em class="parameter"><code>joinable</code></em> is <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, you can wait for this threads termination
calling <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a>. Otherwise the thread will just disappear
when it terminates. If <em class="parameter"><code>bound</code></em> is <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, this thread will be
scheduled in the system scope, otherwise the implementation is free
to do scheduling in the process scope. The first variant is more
expensive resource-wise, but generally faster. On some systems (e.g.
Linux) all threads are bound.
</p>
<p>
The new thread executes the function <em class="parameter"><code>func</code></em> with the argument <em class="parameter"><code>data</code></em>.
If the thread was created successfully, it is returned.
</p>
<p>
<em class="parameter"><code>error</code></em> can be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore errors, or non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to report errors.
The error is set, if and only if the function returns <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>It is not guaranteed that threads with different priorities
really behave accordingly. On some systems (e.g. Linux) there are no
thread priorities. On other systems (e.g. Solaris) there doesn't
seem to be different scheduling for different priorities. All in all
try to avoid being dependent on priorities. Use
<a class="link" href="glib-Threads.html#G-THREAD-PRIORITY-NORMAL:CAPS"><code class="literal">G_THREAD_PRIORITY_NORMAL</code></a> here as a default.</p>
</div>
<p>
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Only use <a class="link" href="glib-Threads.html#g-thread-create-full" title="g_thread_create_full ()"><code class="function">g_thread_create_full()</code></a> if you really can't use
<a class="link" href="glib-Threads.html#g-thread-create" title="g_thread_create ()"><code class="function">g_thread_create()</code></a> instead. <a class="link" href="glib-Threads.html#g-thread-create" title="g_thread_create ()"><code class="function">g_thread_create()</code></a> does not take
<em class="parameter"><code>stack_size</code></em>, <em class="parameter"><code>bound</code></em>, and <em class="parameter"><code>priority</code></em> as arguments, as they should only
be used in cases in which it is unavoidable.</p>
</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
<td>a function to execute in the new thread.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
<td>an argument to supply to the new thread.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>stack_size</code></em> :</span></p></td>
<td>a stack size for the new thread.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>joinable</code></em> :</span></p></td>
<td>should this thread be joinable?</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>bound</code></em> :</span></p></td>
<td>should this thread be bound to a system thread?</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>priority</code></em> :</span></p></td>
<td>a priority for the thread.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
<td>return location for error.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>the new <a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="type">GThread</span></a> on success.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-self"></a><h3>g_thread_self ()</h3>
<pre class="programlisting"><a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="returnvalue">GThread</span></a> *           g_thread_self                       (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
<p>
This functions returns the <a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="type">GThread</span></a> corresponding to the calling
thread.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>the current thread.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-join"></a><h3>g_thread_join ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_thread_join                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="type">GThread</span></a> *thread</code></em>);</pre>
<p>
Waits until <em class="parameter"><code>thread</code></em> finishes, i.e. the function <em class="parameter"><code>func</code></em>, as given to
<a class="link" href="glib-Threads.html#g-thread-create" title="g_thread_create ()"><code class="function">g_thread_create()</code></a>, returns or <a class="link" href="glib-Threads.html#g-thread-exit" title="g_thread_exit ()"><code class="function">g_thread_exit()</code></a> is called by <em class="parameter"><code>thread</code></em>.
All resources of <em class="parameter"><code>thread</code></em> including the <a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="type">GThread</span></a> struct are released.
<em class="parameter"><code>thread</code></em> must have been created with <em class="parameter"><code>joinable</code></em>=<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> in
<a class="link" href="glib-Threads.html#g-thread-create" title="g_thread_create ()"><code class="function">g_thread_create()</code></a>. The value returned by <em class="parameter"><code>func</code></em> or given to
<a class="link" href="glib-Threads.html#g-thread-exit" title="g_thread_exit ()"><code class="function">g_thread_exit()</code></a> by <em class="parameter"><code>thread</code></em> is returned by this function.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>thread</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="type">GThread</span></a> to be waited for.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>the return value of the thread.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-set-priority"></a><h3>g_thread_set_priority ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_thread_set_priority               (<em class="parameter"><code><a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="type">GThread</span></a> *thread</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GThreadPriority" title="enum GThreadPriority"><span class="type">GThreadPriority</span></a> priority</code></em>);</pre>
<p>
Changes the priority of <em class="parameter"><code>thread</code></em> to <em class="parameter"><code>priority</code></em>.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>It is not guaranteed that threads with different
priorities really behave accordingly. On some systems (e.g. Linux)
there are no thread priorities. On other systems (e.g. Solaris) there
doesn't seem to be different scheduling for different priorities. All
in all try to avoid being dependent on priorities.</p>
</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>thread</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="type">GThread</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>priority</code></em> :</span></p></td>
<td>a new priority for <em class="parameter"><code>thread</code></em>.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-yield"></a><h3>g_thread_yield ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_thread_yield                      ();</pre>
<p>
Gives way to other threads waiting to be scheduled.
</p>
<p>
This function is often used as a method to make busy wait less evil.
But in most cases you will encounter, there are better methods to do
that. So in general you shouldn't use this function.
</p>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-exit"></a><h3>g_thread_exit ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_thread_exit                       (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> retval</code></em>);</pre>
<p>
Exits the current thread. If another thread is waiting for that
thread using <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a> and the current thread is joinable, the
waiting thread will be woken up and get <em class="parameter"><code>retval</code></em> as the return value
of <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a>. If the current thread is not joinable, <em class="parameter"><code>retval</code></em>
is ignored. Calling
</p>
<p>
</p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="function"><a href="glib-Threads.html#g-thread-exit">g_thread_exit</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">retval</span><span class="symbol">);</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
</p>
<p>
is equivalent to returning <em class="parameter"><code>retval</code></em> from the function <em class="parameter"><code>func</code></em>, as given
to <a class="link" href="glib-Threads.html#g-thread-create" title="g_thread_create ()"><code class="function">g_thread_create()</code></a>.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Never call <a class="link" href="glib-Threads.html#g-thread-exit" title="g_thread_exit ()"><code class="function">g_thread_exit()</code></a> from within a thread of a
<a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a>, as that will mess up the bookkeeping and lead to funny
and unwanted results.</p>
</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>retval</code></em> :</span></p></td>
<td>the return value of this thread.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-foreach"></a><h3>g_thread_foreach ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_thread_foreach                    (<em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GFunc" title="GFunc ()"><span class="type">GFunc</span></a> thread_func</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
<p>
Call <em class="parameter"><code>thread_func</code></em> on all existing <a class="link" href="glib-Threads.html#GThread" title="struct GThread"><span class="type">GThread</span></a> structures. Note that
threads may decide to exit while <em class="parameter"><code>thread_func</code></em> is running, so
without intimate knowledge about the lifetime of foreign threads,
<em class="parameter"><code>thread_func</code></em> shouldn't access the GThread* pointer passed in as
first argument. However, <em class="parameter"><code>thread_func</code></em> will not be called for threads
which are known to have exited already.
</p>
<p>
Due to thread lifetime checks, this function has an execution complexity
which is quadratic in the number of existing threads.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>thread_func</code></em> :</span></p></td>
<td>function to call for all GThread structures</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
<td>second argument to <em class="parameter"><code>thread_func</code></em>
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.10</p>
</div>
<hr>
<div class="refsect2">
<a name="GMutex"></a><h3>GMutex</h3>
<pre class="programlisting">typedef struct _GMutex GMutex;</pre>
<p>
The <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> struct is an opaque data structure to represent a mutex
(mutual exclusion). It can be used to protect data against shared
access. Take for example the following function:
</p>
<p>
</p>
<div class="example">
<a name="id693688"></a><p class="title"><b>Example 2. A function which will not work in a threaded environment</b></p>
<div class="example-contents">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="type">int</span>
<span class="function">give_me_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal">  </span><span class="keyword">static</span><span class="normal"> </span><span class="type">int</span><span class="normal"> current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span>

<span class="normal">  </span><span class="comment">/* now do a very complicated calculation to calculate the new</span>
<span class="comment">   * number, this might for example be a random number generator</span>
<span class="comment">   */</span>
<span class="normal">  current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="function">calc_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">current_number</span><span class="symbol">);</span>

<span class="normal">  </span><span class="keyword">return</span><span class="normal"> current_number</span><span class="symbol">;</span>
<span class="cbracket">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

</div>
<p><br class="example-break">
</p>
<p>
It is easy to see that this won't work in a multi-threaded
application. There current_number must be protected against shared
access. A first naive implementation would be:
</p>
<p>
</p>
<div class="example">
<a name="id693714"></a><p class="title"><b>Example 3. The wrong way to write a thread-safe function</b></p>
<div class="example-contents">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="type">int</span>
<span class="function">give_me_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal">  </span><span class="keyword">static</span><span class="normal"> </span><span class="type">int</span><span class="normal"> current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span>
<span class="normal">  </span><span class="type">int</span><span class="normal"> ret_val</span><span class="symbol">;</span>
<span class="normal">  </span><span class="keyword">static</span><span class="normal"> <a href="glib-Threads.html#GMutex">GMutex</a> </span><span class="symbol">*</span><span class="normal"> mutex </span><span class="symbol">=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span>

<span class="normal">  </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="normal">mutex</span><span class="symbol">)</span><span class="normal"> mutex </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Threads.html#g-mutex-new">g_mutex_new</a></span><span class="normal"> </span><span class="symbol">();</span>

<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-mutex-lock">g_mutex_lock</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">mutex</span><span class="symbol">);</span>
<span class="normal">  ret_val </span><span class="symbol">=</span><span class="normal"> current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="function">calc_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">current_number</span><span class="symbol">);</span>
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-mutex-unlock">g_mutex_unlock</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">mutex</span><span class="symbol">);</span>

<span class="normal">  </span><span class="keyword">return</span><span class="normal"> ret_val</span><span class="symbol">;</span>
<span class="cbracket">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

</div>
<p><br class="example-break">
</p>
<p>
This looks like it would work, but there is a race condition while
constructing the mutex and this code cannot work reliable. Please do
not use such constructs in your own programs! One working solution
is:
</p>
<p>
</p>
<div class="example">
<a name="id693739"></a><p class="title"><b>Example 4. A correct thread-safe function</b></p>
<div class="example-contents">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="usertype">GMutex</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">give_me_next_number_mutex </span><span class="symbol">=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span>

<span class="comment">/* this function must be called before any call to</span>
<span class="comment"> * give_me_next_number()</span>
<span class="comment"> *</span>
<span class="comment"> * it must be called exactly once.</span>
<span class="comment"> */</span>
<span class="type">void</span>
<span class="function">init_give_me_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal">  </span><span class="function"><a href="glib-Testing.html#g-assert">g_assert</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">give_me_next_number_mutex </span><span class="symbol">==</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>
<span class="normal">  give_me_next_number_mutex </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Threads.html#g-mutex-new">g_mutex_new</a></span><span class="normal"> </span><span class="symbol">();</span>
<span class="cbracket">}</span>

<span class="type">int</span>
<span class="function">give_me_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal">  </span><span class="keyword">static</span><span class="normal"> </span><span class="type">int</span><span class="normal"> current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span>
<span class="normal">  </span><span class="type">int</span><span class="normal"> ret_val</span><span class="symbol">;</span>

<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-mutex-lock">g_mutex_lock</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">give_me_next_number_mutex</span><span class="symbol">);</span>
<span class="normal">  ret_val </span><span class="symbol">=</span><span class="normal"> current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="function">calc_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">current_number</span><span class="symbol">);</span>
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-mutex-unlock">g_mutex_unlock</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">give_me_next_number_mutex</span><span class="symbol">);</span>

<span class="normal">  </span><span class="keyword">return</span><span class="normal"> ret_val</span><span class="symbol">;</span>
<span class="cbracket">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

</div>
<p><br class="example-break">
</p>
<p>
<a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> provides a simpler and safer way of doing this.
</p>
<p>
If you want to use a mutex, and your code should also work without
calling <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> first, then you can not use a <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a>, as
<a class="link" href="glib-Threads.html#g-mutex-new" title="g_mutex_new ()"><code class="function">g_mutex_new()</code></a> requires that the thread system be initialized. Use a
<a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> instead.
</p>
<p>
A <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> should only be accessed via the following functions.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>All of the <code class="function">g_mutex_*</code> functions are
actually macros. Apart from taking their addresses, you can however
use them as if they were functions.</p>
</div>
<p>
</p>
</div>
<hr>
<div class="refsect2">
<a name="g-mutex-new"></a><h3>g_mutex_new ()</h3>
<pre class="programlisting"><a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="returnvalue">GMutex</span></a> *            g_mutex_new                         ();</pre>
<p>
Creates a new <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a>.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>This function will abort if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has not been
called yet.</p>
</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>a new <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a>.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-mutex-lock"></a><h3>g_mutex_lock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_mutex_lock                        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);</pre>
<p>
Locks <em class="parameter"><code>mutex</code></em>. If <em class="parameter"><code>mutex</code></em> is already locked by another thread, the
current thread will block until <em class="parameter"><code>mutex</code></em> is unlocked by the other
thread.
</p>
<p>
This function can be used even if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has not yet been
called, and, in that case, will do nothing.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p><a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> is neither guaranteed to be recursive nor to be
non-recursive, i.e. a thread could deadlock while calling
<a class="link" href="glib-Threads.html#g-mutex-lock" title="g_mutex_lock ()"><code class="function">g_mutex_lock()</code></a>, if it already has locked <em class="parameter"><code>mutex</code></em>. Use
<a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a>, if you need recursive mutexes.</p>
</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a>.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-mutex-trylock"></a><h3>g_mutex_trylock ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_mutex_trylock                     (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);</pre>
<p>
Tries to lock <em class="parameter"><code>mutex</code></em>. If <em class="parameter"><code>mutex</code></em> is already locked by another thread,
it immediately returns <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>. Otherwise it locks <em class="parameter"><code>mutex</code></em> and returns
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>.
</p>
<p>
This function can be used even if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has not yet been
called, and, in that case, will immediately return <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p><a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> is neither guaranteed to be recursive nor to be
non-recursive, i.e. the return value of <a class="link" href="glib-Threads.html#g-mutex-trylock" title="g_mutex_trylock ()"><code class="function">g_mutex_trylock()</code></a> could be
both <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> or <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, if the current thread already has locked
<em class="parameter"><code>mutex</code></em>. Use <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a>, if you need recursive
mutexes.</p>
</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, if <em class="parameter"><code>mutex</code></em> could be locked.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-mutex-unlock"></a><h3>g_mutex_unlock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_mutex_unlock                      (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);</pre>
<p>
Unlocks <em class="parameter"><code>mutex</code></em>. If another thread is blocked in a <a class="link" href="glib-Threads.html#g-mutex-lock" title="g_mutex_lock ()"><code class="function">g_mutex_lock()</code></a>
call for <em class="parameter"><code>mutex</code></em>, it will be woken and can lock <em class="parameter"><code>mutex</code></em> itself.
</p>
<p>
This function can be used even if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has not yet been
called, and, in that case, will do nothing.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a>.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-mutex-free"></a><h3>g_mutex_free ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_mutex_free                        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);</pre>
<p>
Destroys <em class="parameter"><code>mutex</code></em>.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Calling <a class="link" href="glib-Threads.html#g-mutex-free" title="g_mutex_free ()"><code class="function">g_mutex_free()</code></a> on a locked mutex may result in
undefined behaviour.</p>
</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a>.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="GStaticMutex"></a><h3>GStaticMutex</h3>
<pre class="programlisting">typedef struct _GStaticMutex GStaticMutex;</pre>
<p>
A <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> works like a <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a>, but it has one significant
advantage. It doesn't need to be created at run-time like a <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a>,
but can be defined at compile-time. Here is a shorter, easier and
safer version of our <code class="function"><code class="function">give_me_next_number()</code></code>
example:
</p>
<p>
</p>
<div class="example">
<a name="id694564"></a><p class="title"><b>Example 5. 
  Using <span class="structname">GStaticMutex</span>
  to simplify thread-safe programming
 </b></p>
<div class="example-contents">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="type">int</span>
<span class="function">give_me_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal">  </span><span class="keyword">static</span><span class="normal"> </span><span class="type">int</span><span class="normal"> current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span>
<span class="normal">  </span><span class="type">int</span><span class="normal"> ret_val</span><span class="symbol">;</span>
<span class="normal">  </span><span class="keyword">static</span><span class="normal"> </span><span class="usertype">GStaticMutex</span><span class="normal"> mutex </span><span class="symbol">=</span><span class="normal"> <a href="glib-Threads.html#G-STATIC-MUTEX-INIT:CAPS">G_STATIC_MUTEX_INIT</a></span><span class="symbol">;</span>

<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-static-mutex-lock">g_static_mutex_lock</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">mutex</span><span class="symbol">);</span>
<span class="normal">  ret_val </span><span class="symbol">=</span><span class="normal"> current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="function">calc_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">current_number</span><span class="symbol">);</span>
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-static-mutex-unlock">g_static_mutex_unlock</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">mutex</span><span class="symbol">);</span>

<span class="normal">  </span><span class="keyword">return</span><span class="normal"> ret_val</span><span class="symbol">;</span>
<span class="cbracket">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

</div>
<p><br class="example-break">
</p>
<p>
Sometimes you would like to dynamically create a mutex. If you don't
want to require prior calling to <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a>, because your code
should also be usable in non-threaded programs, you are not able to
use <a class="link" href="glib-Threads.html#g-mutex-new" title="g_mutex_new ()"><code class="function">g_mutex_new()</code></a> and thus <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a>, as that requires a prior call to
<a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a>. In theses cases you can also use a <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>.
It must be initialized with <a class="link" href="glib-Threads.html#g-static-mutex-init" title="g_static_mutex_init ()"><code class="function">g_static_mutex_init()</code></a> before using it
and freed with with <a class="link" href="glib-Threads.html#g-static-mutex-free" title="g_static_mutex_free ()"><code class="function">g_static_mutex_free()</code></a> when not needed anymore to
free up any allocated resources.
</p>
<p>
Even though <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> is not opaque, it should only be used with
the following functions, as it is defined differently on different
platforms.
</p>
<p>
All of the <code class="function">g_static_mutex_*</code> functions apart
from <code class="function">g_static_mutex_get_mutex</code> can also be used
even if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has not yet been called. Then they do
nothing, apart from <code class="function">g_static_mutex_trylock</code>,
which does nothing but returning <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>All of the <code class="function">g_static_mutex_*</code>
functions are actually macros. Apart from taking their addresses, you
can however use them as if they were functions.</p>
</div>
<p>
</p>
</div>
<hr>
<div class="refsect2">
<a name="G-STATIC-MUTEX-INIT:CAPS"></a><h3>G_STATIC_MUTEX_INIT</h3>
<pre class="programlisting">#define G_STATIC_MUTEX_INIT
</pre>
<p>
A <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> must be initialized with this macro, before it can
be used. This macro can used be to initialize a variable, but it
cannot be assigned to a variable. In that case you have to use
<a class="link" href="glib-Threads.html#g-static-mutex-init" title="g_static_mutex_init ()"><code class="function">g_static_mutex_init()</code></a>.
</p>
<p>
</p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="usertype">GStaticMutex</span><span class="normal"> my_mutex </span><span class="symbol">=</span><span class="normal"> <a href="glib-Threads.html#G-STATIC-MUTEX-INIT:CAPS">G_STATIC_MUTEX_INIT</a></span><span class="symbol">;</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
</p>
</div>
<hr>
<div class="refsect2">
<a name="g-static-mutex-init"></a><h3>g_static_mutex_init ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_mutex_init                 (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> *mutex</code></em>);</pre>
<p>
Initializes <em class="parameter"><code>mutex</code></em>. Alternatively you can initialize it with
<a class="link" href="glib-Threads.html#G-STATIC-MUTEX-INIT:CAPS" title="G_STATIC_MUTEX_INIT"><span class="type">G_STATIC_MUTEX_INIT</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> to be initialized.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-mutex-lock"></a><h3>g_static_mutex_lock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_mutex_lock                 (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> *mutex</code></em>);</pre>
<p>
Works like <a class="link" href="glib-Threads.html#g-mutex-lock" title="g_mutex_lock ()"><code class="function">g_mutex_lock()</code></a>, but for a <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-mutex-trylock"></a><h3>g_static_mutex_trylock ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_static_mutex_trylock              (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> *mutex</code></em>);</pre>
<p>
Works like <a class="link" href="glib-Threads.html#g-mutex-trylock" title="g_mutex_trylock ()"><code class="function">g_mutex_trylock()</code></a>, but for a <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, if the <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> could be locked.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-mutex-unlock"></a><h3>g_static_mutex_unlock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_mutex_unlock               (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> *mutex</code></em>);</pre>
<p>
Works like <a class="link" href="glib-Threads.html#g-mutex-unlock" title="g_mutex_unlock ()"><code class="function">g_mutex_unlock()</code></a>, but for a <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-mutex-get-mutex"></a><h3>g_static_mutex_get_mutex ()</h3>
<pre class="programlisting"><a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="returnvalue">GMutex</span></a> *            g_static_mutex_get_mutex            (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> *mutex</code></em>);</pre>
<p>
For some operations (like <a class="link" href="glib-Threads.html#g-cond-wait" title="g_cond_wait ()"><code class="function">g_cond_wait()</code></a>) you must have a <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a>
instead of a <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>. This function will return the
corresponding <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> for <em class="parameter"><code>mutex</code></em>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>the <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> corresponding to <em class="parameter"><code>mutex</code></em>.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-mutex-free"></a><h3>g_static_mutex_free ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_mutex_free                 (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> *mutex</code></em>);</pre>
<p>
Releases all resources allocated to <em class="parameter"><code>mutex</code></em>.
</p>
<p>
You don't have to call this functions for a <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> with an
unbounded lifetime, i.e. objects declared 'static', but if you have
a <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> as a member of a structure and the structure is
freed, you should also free the <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Calling <a class="link" href="glib-Threads.html#g-static-mutex-free" title="g_static_mutex_free ()"><code class="function">g_static_mutex_free()</code></a> on a locked mutex may
result in undefined behaviour.</p>
</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a> to be freed.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="G-LOCK-DEFINE:CAPS"></a><h3>G_LOCK_DEFINE()</h3>
<pre class="programlisting">#define G_LOCK_DEFINE(name)    
</pre>
<p>
The <code class="literal">G_LOCK_</code>* macros provide a convenient interface to <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>
with the advantage that they will expand to nothing in programs
compiled against a thread-disabled GLib, saving code and memory
there. <a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a> defines a lock. It can appear anywhere
variable definitions may appear in programs, i.e. in the first block
of a function or outside of functions. The <em class="parameter"><code>name</code></em> parameter will be
mangled to get the name of the <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>. This means that you
can use names of existing variables as the parameter - e.g. the name
of the variable you intent to protect with the lock. Look at our
<code class="function"><code class="function">give_me_next_number()</code></code> example using the
<code class="literal">G_LOCK_</code>* macros:
</p>
<p>
</p>
<div class="example">
<a name="id695614"></a><p class="title"><b>Example 6. Using the <code class="literal">G_LOCK_</code>* convenience macros</b></p>
<div class="example-contents">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="function"><a href="glib-Threads.html#G-LOCK-DEFINE:CAPS">G_LOCK_DEFINE</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">current_number</span><span class="symbol">);</span>

<span class="type">int</span>
<span class="function">give_me_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal">  </span><span class="keyword">static</span><span class="normal"> </span><span class="type">int</span><span class="normal"> current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span>
<span class="normal">  </span><span class="type">int</span><span class="normal"> ret_val</span><span class="symbol">;</span>

<span class="normal">  </span><span class="function"><a href="glib-Threads.html#G-LOCK:CAPS">G_LOCK</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">current_number</span><span class="symbol">);</span>
<span class="normal">  ret_val </span><span class="symbol">=</span><span class="normal"> current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="function">calc_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">current_number</span><span class="symbol">);</span>
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#G-UNLOCK:CAPS">G_UNLOCK</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">current_number</span><span class="symbol">);</span>

<span class="normal">  </span><span class="keyword">return</span><span class="normal"> ret_val</span><span class="symbol">;</span>
<span class="cbracket">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

</div>
<p><br class="example-break">
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
<td>the name of the lock.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="G-LOCK-DEFINE-STATIC:CAPS"></a><h3>G_LOCK_DEFINE_STATIC()</h3>
<pre class="programlisting">#define G_LOCK_DEFINE_STATIC(name)
</pre>
<p>
This works like <a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a>, but it creates a static object.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
<td>the name of the lock.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="G-LOCK-EXTERN:CAPS"></a><h3>G_LOCK_EXTERN()</h3>
<pre class="programlisting">#define G_LOCK_EXTERN(name)    
</pre>
<p>
This declares a lock, that is defined with <a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a> in another
module.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
<td>the name of the lock.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="G-LOCK:CAPS"></a><h3>G_LOCK()</h3>
<pre class="programlisting">#define G_LOCK(name)
</pre>
<p>
Works like <a class="link" href="glib-Threads.html#g-mutex-lock" title="g_mutex_lock ()"><code class="function">g_mutex_lock()</code></a>, but for a lock defined with
<a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
<td>the name of the lock.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="G-TRYLOCK:CAPS"></a><h3>G_TRYLOCK()</h3>
<pre class="programlisting">#define G_TRYLOCK(name)
</pre>
<p>
Works like <a class="link" href="glib-Threads.html#g-mutex-trylock" title="g_mutex_trylock ()"><code class="function">g_mutex_trylock()</code></a>, but for a lock defined with
<a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
<td>the name of the lock.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, if the lock could be locked.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="G-UNLOCK:CAPS"></a><h3>G_UNLOCK()</h3>
<pre class="programlisting">#define G_UNLOCK(name)
</pre>
<p>
Works like <a class="link" href="glib-Threads.html#g-mutex-unlock" title="g_mutex_unlock ()"><code class="function">g_mutex_unlock()</code></a>, but for a lock defined with
<a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
<td>the name of the lock.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="GStaticRecMutex"></a><h3>struct GStaticRecMutex</h3>
<pre class="programlisting">struct GStaticRecMutex {
};
</pre>
<p>
A <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> works like a <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>, but it can be locked
multiple times by one thread. If you enter it n times, you have to
unlock it n times again to let other threads lock it. An exception
is the function <a class="link" href="glib-Threads.html#g-static-rec-mutex-unlock-full" title="g_static_rec_mutex_unlock_full ()"><code class="function">g_static_rec_mutex_unlock_full()</code></a>: that allows you to
unlock a <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> completely returning the depth, (i.e. the
number of times this mutex was locked). The depth can later be used
to restore the state of the <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> by calling
<a class="link" href="glib-Threads.html#g-static-rec-mutex-lock-full" title="g_static_rec_mutex_lock_full ()"><code class="function">g_static_rec_mutex_lock_full()</code></a>.
</p>
<p>
Even though <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> is not opaque, it should only be used
with the following functions.
</p>
<p>
All of the <code class="function">g_static_rec_mutex_*</code> functions can
be used even if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has not been called. Then they do
nothing, apart from <code class="function">g_static_rec_mutex_trylock</code>,
which does nothing but returning <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>.
</p>
</div>
<hr>
<div class="refsect2">
<a name="G-STATIC-REC-MUTEX-INIT:CAPS"></a><h3>G_STATIC_REC_MUTEX_INIT</h3>
<pre class="programlisting">#define G_STATIC_REC_MUTEX_INIT { G_STATIC_MUTEX_INIT }
</pre>
<p>
A <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> must be initialized with this macro before it can
be used. This macro can used be to initialize a variable, but it
cannot be assigned to a variable. In that case you have to use
<a class="link" href="glib-Threads.html#g-static-rec-mutex-init" title="g_static_rec_mutex_init ()"><code class="function">g_static_rec_mutex_init()</code></a>.
</p>
<p>
</p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="usertype">GStaticRecMutex</span><span class="normal"> my_mutex </span><span class="symbol">=</span><span class="normal"> <a href="glib-Threads.html#G-STATIC-REC-MUTEX-INIT:CAPS">G_STATIC_REC_MUTEX_INIT</a></span><span class="symbol">;</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
</p>
</div>
<hr>
<div class="refsect2">
<a name="g-static-rec-mutex-init"></a><h3>g_static_rec_mutex_init ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_rec_mutex_init             (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> *mutex</code></em>);</pre>
<p>
A <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> must be initialized with this function before it
can be used. Alternatively you can initialize it with
<a class="link" href="glib-Threads.html#G-STATIC-REC-MUTEX-INIT:CAPS" title="G_STATIC_REC_MUTEX_INIT"><span class="type">G_STATIC_REC_MUTEX_INIT</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> to be initialized.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-rec-mutex-lock"></a><h3>g_static_rec_mutex_lock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_rec_mutex_lock             (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> *mutex</code></em>);</pre>
<p>
Locks <em class="parameter"><code>mutex</code></em>. If <em class="parameter"><code>mutex</code></em> is already locked by another thread, the
current thread will block until <em class="parameter"><code>mutex</code></em> is unlocked by the other
thread. If <em class="parameter"><code>mutex</code></em> is already locked by the calling thread, this
functions increases the depth of <em class="parameter"><code>mutex</code></em> and returns immediately.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> to lock.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-rec-mutex-trylock"></a><h3>g_static_rec_mutex_trylock ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_static_rec_mutex_trylock          (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> *mutex</code></em>);</pre>
<p>
Tries to lock <em class="parameter"><code>mutex</code></em>. If <em class="parameter"><code>mutex</code></em> is already locked by another thread,
it immediately returns <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>. Otherwise it locks <em class="parameter"><code>mutex</code></em> and returns
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>. If <em class="parameter"><code>mutex</code></em> is already locked by the calling thread, this
functions increases the depth of <em class="parameter"><code>mutex</code></em> and immediately returns
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> to lock.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, if <em class="parameter"><code>mutex</code></em> could be locked.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-rec-mutex-unlock"></a><h3>g_static_rec_mutex_unlock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_rec_mutex_unlock           (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> *mutex</code></em>);</pre>
<p>
Unlocks <em class="parameter"><code>mutex</code></em>. Another thread will be allowed to lock <em class="parameter"><code>mutex</code></em> only
when it has been unlocked as many times as it had been locked
before. If <em class="parameter"><code>mutex</code></em> is completely unlocked and another thread is
blocked in a <a class="link" href="glib-Threads.html#g-static-rec-mutex-lock" title="g_static_rec_mutex_lock ()"><code class="function">g_static_rec_mutex_lock()</code></a> call for <em class="parameter"><code>mutex</code></em>, it will be
woken and can lock <em class="parameter"><code>mutex</code></em> itself.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> to unlock.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-rec-mutex-lock-full"></a><h3>g_static_rec_mutex_lock_full ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_rec_mutex_lock_full        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> *mutex</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> depth</code></em>);</pre>
<p>
Works like calling <a class="link" href="glib-Threads.html#g-static-rec-mutex-lock" title="g_static_rec_mutex_lock ()"><code class="function">g_static_rec_mutex_lock()</code></a> for <em class="parameter"><code>mutex</code></em> <em class="parameter"><code>depth</code></em> times.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> to lock.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>depth</code></em> :</span></p></td>
<td>number of times this mutex has to be unlocked to be
completely unlocked.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-rec-mutex-unlock-full"></a><h3>g_static_rec_mutex_unlock_full ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               g_static_rec_mutex_unlock_full      (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> *mutex</code></em>);</pre>
<p>
Completely unlocks <em class="parameter"><code>mutex</code></em>. If another thread is blocked in a
<a class="link" href="glib-Threads.html#g-static-rec-mutex-lock" title="g_static_rec_mutex_lock ()"><code class="function">g_static_rec_mutex_lock()</code></a> call for <em class="parameter"><code>mutex</code></em>, it will be woken and can
lock <em class="parameter"><code>mutex</code></em> itself. This function returns the number of times that
<em class="parameter"><code>mutex</code></em> has been locked by the current thread. To restore the state
before the call to <a class="link" href="glib-Threads.html#g-static-rec-mutex-unlock-full" title="g_static_rec_mutex_unlock_full ()"><code class="function">g_static_rec_mutex_unlock_full()</code></a> you can call
<a class="link" href="glib-Threads.html#g-static-rec-mutex-lock-full" title="g_static_rec_mutex_lock_full ()"><code class="function">g_static_rec_mutex_lock_full()</code></a> with the depth returned by this
function.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> to completely unlock.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>number of times <em class="parameter"><code>mutex</code></em> has been locked by the current
thread.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-rec-mutex-free"></a><h3>g_static_rec_mutex_free ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_rec_mutex_free             (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> *mutex</code></em>);</pre>
<p>
Releases all resources allocated to a <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a>.
</p>
<p>
You don't have to call this functions for a <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> with an
unbounded lifetime, i.e. objects declared 'static', but if you have
a <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> as a member of a structure and the structure is
freed, you should also free the <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticRecMutex" title="struct GStaticRecMutex"><span class="type">GStaticRecMutex</span></a> to be freed.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="GStaticRWLock"></a><h3>struct GStaticRWLock</h3>
<pre class="programlisting">struct GStaticRWLock {
};
</pre>
<p>
The <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> struct represents a read-write lock. A read-write
lock can be used for protecting data that some portions of code only
read from, while others also write. In such situations it is
desirable that several readers can read at once, whereas of course
only one writer may write at a time. Take a look at the following
example:
</p>
<p>
</p>
<div class="example">
<a name="id697228"></a><p class="title"><b>Example 7. An array with access functions</b></p>
<div class="example-contents">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="usertype">GStaticRWLock</span><span class="normal"> rwlock </span><span class="symbol">=</span><span class="normal"> <a href="glib-Threads.html#G-STATIC-RW-LOCK-INIT:CAPS">G_STATIC_RW_LOCK_INIT</a></span><span class="symbol">;</span>
<span class="usertype">GPtrArray</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">array</span><span class="symbol">;</span>

<span class="normal"><a href="glib-Basic-Types.html#gpointer">gpointer</a></span>
<span class="function">my_array_get</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">guint</span><span class="normal"> index</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal">  </span><span class="usertype">gpointer</span><span class="normal"> retval </span><span class="symbol">=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span>

<span class="normal">  </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="normal">array</span><span class="symbol">)</span>
<span class="normal">    </span><span class="keyword">return</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span>

<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-static-rw-lock-reader-lock">g_static_rw_lock_reader_lock</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">rwlock</span><span class="symbol">);</span>
<span class="normal">  </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">index </span><span class="symbol">&lt;</span><span class="normal"> array</span><span class="symbol">-&gt;</span><span class="normal">len</span><span class="symbol">)</span>
<span class="normal">    retval </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Pointer-Arrays.html#g-ptr-array-index">g_ptr_array_index</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">array</span><span class="symbol">,</span><span class="normal"> index</span><span class="symbol">);</span>
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-static-rw-lock-reader-unlock">g_static_rw_lock_reader_unlock</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">rwlock</span><span class="symbol">);</span>

<span class="normal">  </span><span class="keyword">return</span><span class="normal"> retval</span><span class="symbol">;</span>
<span class="cbracket">}</span>

<span class="type">void</span>
<span class="function">my_array_set</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">guint</span><span class="normal"> index</span><span class="symbol">,</span><span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> data</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-static-rw-lock-writer-lock">g_static_rw_lock_writer_lock</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">rwlock</span><span class="symbol">);</span>

<span class="normal">  </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="normal">array</span><span class="symbol">)</span>
<span class="normal">    array </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Pointer-Arrays.html#g-ptr-array-new">g_ptr_array_new</a></span><span class="normal"> </span><span class="symbol">();</span>

<span class="normal">  </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">index </span><span class="symbol">&gt;=</span><span class="normal"> array</span><span class="symbol">-&gt;</span><span class="normal">len</span><span class="symbol">)</span>
<span class="normal">    </span><span class="function"><a href="glib-Pointer-Arrays.html#g-ptr-array-set-size">g_ptr_array_set_size</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">array</span><span class="symbol">,</span><span class="normal"> index</span><span class="symbol">+</span><span class="number">1</span><span class="symbol">);</span>
<span class="normal">  </span><span class="function"><a href="glib-Pointer-Arrays.html#g-ptr-array-index">g_ptr_array_index</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">array</span><span class="symbol">,</span><span class="normal"> index</span><span class="symbol">)</span><span class="normal"> </span><span class="symbol">=</span><span class="normal"> data</span><span class="symbol">;</span>

<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-static-rw-lock-writer-unlock">g_static_rw_lock_writer_unlock</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">rwlock</span><span class="symbol">);</span>
<span class="cbracket">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

</div>
<p><br class="example-break">
</p>
<p>
This example shows an array which can be accessed by many readers
(the <code class="function"><code class="function">my_array_get()</code></code> function) simultaneously,
whereas the writers (the <code class="function"><code class="function">my_array_set()</code></code>
function) will only be allowed once at a time and only if no readers
currently access the array. This is because of the potentially
dangerous resizing of the array. Using these functions is fully
multi-thread safe now.
</p>
<p>
Most of the time, writers should have precedence over readers. That
means, for this implementation, that as soon as a writer wants to
lock the data, no other reader is allowed to lock the data, whereas,
of course, the readers that already have locked the data are allowed
to finish their operation. As soon as the last reader unlocks the
data, the writer will lock it.
</p>
<p>
Even though <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> is not opaque, it should only be used
with the following functions.
</p>
<p>
All of the <code class="function">g_static_rw_lock_*</code> functions can be
used even if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has not been called. Then they do
nothing, apart from <code class="function">g_static_rw_lock_*_trylock</code>,
which does nothing but returning <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>A read-write lock has a higher overhead than a mutex. For
example, both <a class="link" href="glib-Threads.html#g-static-rw-lock-reader-lock" title="g_static_rw_lock_reader_lock ()"><code class="function">g_static_rw_lock_reader_lock()</code></a> and
<a class="link" href="glib-Threads.html#g-static-rw-lock-reader-unlock" title="g_static_rw_lock_reader_unlock ()"><code class="function">g_static_rw_lock_reader_unlock()</code></a> have to lock and unlock a
<a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>, so it takes at least twice the time to lock and unlock
a <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> that it does to lock and unlock a <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>. So
only data structures that are accessed by multiple readers, and which
keep the lock for a considerable time justify a <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a>. The
above example most probably would fare better with a
<a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>.</p>
</div>
<p>
</p>
</div>
<hr>
<div class="refsect2">
<a name="G-STATIC-RW-LOCK-INIT:CAPS"></a><h3>G_STATIC_RW_LOCK_INIT</h3>
<pre class="programlisting">#define G_STATIC_RW_LOCK_INIT { G_STATIC_MUTEX_INIT, NULL, NULL, 0, FALSE, 0, 0 }
</pre>
<p>
A <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> must be initialized with this macro before it can
be used. This macro can used be to initialize a variable, but it
cannot be assigned to a variable. In that case you have to use
<a class="link" href="glib-Threads.html#g-static-rw-lock-init" title="g_static_rw_lock_init ()"><code class="function">g_static_rw_lock_init()</code></a>.
</p>
<p>
</p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="usertype">GStaticRWLock</span><span class="normal"> my_lock </span><span class="symbol">=</span><span class="normal"> <a href="glib-Threads.html#G-STATIC-RW-LOCK-INIT:CAPS">G_STATIC_RW_LOCK_INIT</a></span><span class="symbol">;</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
</p>
</div>
<hr>
<div class="refsect2">
<a name="g-static-rw-lock-init"></a><h3>g_static_rw_lock_init ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_rw_lock_init               (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> *lock</code></em>);</pre>
<p>
A <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> must be initialized with this function before it
can be used. Alternatively you can initialize it with
<a class="link" href="glib-Threads.html#G-STATIC-RW-LOCK-INIT:CAPS" title="G_STATIC_RW_LOCK_INIT"><span class="type">G_STATIC_RW_LOCK_INIT</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>lock</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> to be initialized.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-rw-lock-reader-lock"></a><h3>g_static_rw_lock_reader_lock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_rw_lock_reader_lock        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> *lock</code></em>);</pre>
<p>
Locks <em class="parameter"><code>lock</code></em> for reading. There may be unlimited concurrent locks for
reading of a <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> at the same time.  If <em class="parameter"><code>lock</code></em> is already
locked for writing by another thread or if another thread is already
waiting to lock <em class="parameter"><code>lock</code></em> for writing, this function will block until
<em class="parameter"><code>lock</code></em> is unlocked by the other writing thread and no other writing
threads want to lock <em class="parameter"><code>lock</code></em>. This lock has to be unlocked by
<a class="link" href="glib-Threads.html#g-static-rw-lock-reader-unlock" title="g_static_rw_lock_reader_unlock ()"><code class="function">g_static_rw_lock_reader_unlock()</code></a>.
</p>
<p>
<a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> is not recursive. It might seem to be possible to
recursively lock for reading, but that can result in a deadlock, due
to writer preference.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>lock</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> to lock for reading.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-rw-lock-reader-trylock"></a><h3>g_static_rw_lock_reader_trylock ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_static_rw_lock_reader_trylock     (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> *lock</code></em>);</pre>
<p>
Tries to lock <em class="parameter"><code>lock</code></em> for reading. If <em class="parameter"><code>lock</code></em> is already locked for
writing by another thread or if another thread is already waiting to
lock <em class="parameter"><code>lock</code></em> for writing, immediately returns <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>. Otherwise locks
<em class="parameter"><code>lock</code></em> for reading and returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>. This lock has to be unlocked by
<a class="link" href="glib-Threads.html#g-static-rw-lock-reader-unlock" title="g_static_rw_lock_reader_unlock ()"><code class="function">g_static_rw_lock_reader_unlock()</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>lock</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> to lock for reading.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, if <em class="parameter"><code>lock</code></em> could be locked for reading.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-rw-lock-reader-unlock"></a><h3>g_static_rw_lock_reader_unlock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_rw_lock_reader_unlock      (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> *lock</code></em>);</pre>
<p>
Unlocks <em class="parameter"><code>lock</code></em>. If a thread waits to lock <em class="parameter"><code>lock</code></em> for writing and all
locks for reading have been unlocked, the waiting thread is woken up
and can lock <em class="parameter"><code>lock</code></em> for writing.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>lock</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> to unlock after reading.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-rw-lock-writer-lock"></a><h3>g_static_rw_lock_writer_lock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_rw_lock_writer_lock        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> *lock</code></em>);</pre>
<p>
Locks <em class="parameter"><code>lock</code></em> for writing. If <em class="parameter"><code>lock</code></em> is already locked for writing or
reading by other threads, this function will block until <em class="parameter"><code>lock</code></em> is
completely unlocked and then lock <em class="parameter"><code>lock</code></em> for writing. While this
functions waits to lock <em class="parameter"><code>lock</code></em>, no other thread can lock <em class="parameter"><code>lock</code></em> for
reading. When <em class="parameter"><code>lock</code></em> is locked for writing, no other thread can lock
<em class="parameter"><code>lock</code></em> (neither for reading nor writing). This lock has to be
unlocked by <a class="link" href="glib-Threads.html#g-static-rw-lock-writer-unlock" title="g_static_rw_lock_writer_unlock ()"><code class="function">g_static_rw_lock_writer_unlock()</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>lock</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> to lock for writing.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-rw-lock-writer-trylock"></a><h3>g_static_rw_lock_writer_trylock ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_static_rw_lock_writer_trylock     (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> *lock</code></em>);</pre>
<p>
Tries to lock <em class="parameter"><code>lock</code></em> for writing. If <em class="parameter"><code>lock</code></em> is already locked (for
either reading or writing) by another thread, it immediately returns
<a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>. Otherwise it locks <em class="parameter"><code>lock</code></em> for writing and returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>. This
lock has to be unlocked by <a class="link" href="glib-Threads.html#g-static-rw-lock-writer-unlock" title="g_static_rw_lock_writer_unlock ()"><code class="function">g_static_rw_lock_writer_unlock()</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>lock</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> to lock for writing.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, if <em class="parameter"><code>lock</code></em> could be locked for writing.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-rw-lock-writer-unlock"></a><h3>g_static_rw_lock_writer_unlock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_rw_lock_writer_unlock      (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> *lock</code></em>);</pre>
<p>
Unlocks <em class="parameter"><code>lock</code></em>. If a thread is waiting to lock <em class="parameter"><code>lock</code></em> for writing and
all locks for reading have been unlocked, the waiting thread is
woken up and can lock <em class="parameter"><code>lock</code></em> for writing. If no thread is waiting to
lock <em class="parameter"><code>lock</code></em> for writing, and some thread or threads are waiting to
lock <em class="parameter"><code>lock</code></em> for reading, the waiting threads are woken up and can
lock <em class="parameter"><code>lock</code></em> for reading.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>lock</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> to unlock after writing.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-rw-lock-free"></a><h3>g_static_rw_lock_free ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_rw_lock_free               (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> *lock</code></em>);</pre>
<p>
Releases all resources allocated to <em class="parameter"><code>lock</code></em>.
</p>
<p>
You don't have to call this functions for a <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> with an
unbounded lifetime, i.e. objects declared 'static', but if you have
a <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> as a member of a structure, and the structure is
freed, you should also free the <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>lock</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticRWLock" title="struct GStaticRWLock"><span class="type">GStaticRWLock</span></a> to be freed.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="GCond"></a><h3>GCond</h3>
<pre class="programlisting">typedef struct _GCond GCond;</pre>
<p>
The <a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a> struct is an opaque data structure that represents a
condition. Threads can block on a <a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a> if they find a certain
condition to be false. If other threads change the state of this
condition they signal the <a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a>, and that causes the waiting
threads to be woken up.
</p>
<p>
</p>
<div class="example">
<a name="id698631"></a><p class="title"><b>Example 8. 
  Using GCond to block a thread until a condition is satisfied
 </b></p>
<div class="example-contents">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="normal"><a href="glib-Threads.html#GCond">GCond</a></span><span class="symbol">*</span><span class="normal"> data_cond </span><span class="symbol">=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span><span class="normal"> </span><span class="comment">/* Must be initialized somewhere */</span>
<span class="normal"><a href="glib-Threads.html#GMutex">GMutex</a></span><span class="symbol">*</span><span class="normal"> data_mutex </span><span class="symbol">=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span><span class="normal"> </span><span class="comment">/* Must be initialized somewhere */</span>
<span class="usertype">gpointer</span><span class="normal"> current_data </span><span class="symbol">=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span>

<span class="type">void</span>
<span class="function">push_data</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">gpointer</span><span class="normal"> data</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-mutex-lock">g_mutex_lock</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">data_mutex</span><span class="symbol">);</span>
<span class="normal">  current_data </span><span class="symbol">=</span><span class="normal"> data</span><span class="symbol">;</span>
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-cond-signal">g_cond_signal</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">data_cond</span><span class="symbol">);</span>
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-mutex-unlock">g_mutex_unlock</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">data_mutex</span><span class="symbol">);</span>
<span class="cbracket">}</span>

<span class="normal"><a href="glib-Basic-Types.html#gpointer">gpointer</a></span>
<span class="function">pop_data</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal">  </span><span class="usertype">gpointer</span><span class="normal"> data</span><span class="symbol">;</span>

<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-mutex-lock">g_mutex_lock</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">data_mutex</span><span class="symbol">);</span>
<span class="normal">  </span><span class="keyword">while</span><span class="normal"> </span><span class="symbol">(!</span><span class="normal">current_data</span><span class="symbol">)</span>
<span class="normal">    </span><span class="function"><a href="glib-Threads.html#g-cond-wait">g_cond_wait</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">data_cond</span><span class="symbol">,</span><span class="normal"> data_mutex</span><span class="symbol">);</span>
<span class="normal">  data </span><span class="symbol">=</span><span class="normal"> current_data</span><span class="symbol">;</span>
<span class="normal">  current_data </span><span class="symbol">=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span>
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-mutex-unlock">g_mutex_unlock</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">data_mutex</span><span class="symbol">);</span>

<span class="normal">  </span><span class="keyword">return</span><span class="normal"> data</span><span class="symbol">;</span>
<span class="cbracket">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

</div>
<p><br class="example-break">
</p>
<p>
Whenever a thread calls <code class="function"><code class="function">pop_data()</code></code> now, it will
wait until current_data is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, i.e. until some other thread
has called <code class="function"><code class="function">push_data()</code></code>.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>It is important to use the <a class="link" href="glib-Threads.html#g-cond-wait" title="g_cond_wait ()"><code class="function">g_cond_wait()</code></a> and
<a class="link" href="glib-Threads.html#g-cond-timed-wait" title="g_cond_timed_wait ()"><code class="function">g_cond_timed_wait()</code></a> functions only inside a loop which checks for the
condition to be true.  It is not guaranteed that the waiting thread
will find the condition fulfilled after it wakes up, even if the
signaling thread left the condition in that state: another thread may
have altered the condition before the waiting thread got the chance
to be woken up, even if the condition itself is protected by a
<a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a>, like above.</p>
</div>
<p>
</p>
<p>
A <a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a> should only be accessed via the following functions.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>All of the <code class="function">g_cond_*</code> functions are
actually macros. Apart from taking their addresses, you can however
use them as if they were functions.</p>
</div>
<p>
</p>
</div>
<hr>
<div class="refsect2">
<a name="g-cond-new"></a><h3>g_cond_new ()</h3>
<pre class="programlisting"><a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="returnvalue">GCond</span></a>*              g_cond_new                          ();</pre>
<p>
Creates a new <a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a>. This function will abort, if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a>
has not been called yet.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>a new <a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a>.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-cond-signal"></a><h3>g_cond_signal ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_cond_signal                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a> *cond</code></em>);</pre>
<p>
If threads are waiting for <em class="parameter"><code>cond</code></em>, exactly one of them is woken up.
It is good practice to hold the same lock as the waiting thread
while calling this function, though not required.
</p>
<p>
This function can be used even if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has not yet been
called, and, in that case, will do nothing.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a>.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-cond-broadcast"></a><h3>g_cond_broadcast ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_cond_broadcast                    (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a> *cond</code></em>);</pre>
<p>
If threads are waiting for <em class="parameter"><code>cond</code></em>, all of them are woken up. It is
good practice to lock the same mutex as the waiting threads, while
calling this function, though not required.
</p>
<p>
This function can be used even if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has not yet been
called, and, in that case, will do nothing.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a>.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-cond-wait"></a><h3>g_cond_wait ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_cond_wait                         (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a> *cond</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);</pre>
<p>
Waits until this thread is woken up on <em class="parameter"><code>cond</code></em>. The <em class="parameter"><code>mutex</code></em> is unlocked
before falling asleep and locked again before resuming.
</p>
<p>
This function can be used even if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has not yet been
called, and, in that case, will immediately return.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a>, that is currently locked.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-cond-timed-wait"></a><h3>g_cond_timed_wait ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_cond_timed_wait                   (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a> *cond</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> *mutex</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Date-and-Time-Functions.html#GTimeVal" title="struct GTimeVal"><span class="type">GTimeVal</span></a> *abs_time</code></em>);</pre>
<p>
Waits until this thread is woken up on <em class="parameter"><code>cond</code></em>, but not longer than
until the time specified by <em class="parameter"><code>abs_time</code></em>. The <em class="parameter"><code>mutex</code></em> is unlocked before
falling asleep and locked again before resuming.
</p>
<p>
If <em class="parameter"><code>abs_time</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, <a class="link" href="glib-Threads.html#g-cond-timed-wait" title="g_cond_timed_wait ()"><code class="function">g_cond_timed_wait()</code></a> acts like <a class="link" href="glib-Threads.html#g-cond-wait" title="g_cond_wait ()"><code class="function">g_cond_wait()</code></a>.
</p>
<p>
This function can be used even if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has not yet been
called, and, in that case, will immediately return <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>.
</p>
<p>
To easily calculate <em class="parameter"><code>abs_time</code></em> a combination of <a class="link" href="glib-Date-and-Time-Functions.html#g-get-current-time" title="g_get_current_time ()"><code class="function">g_get_current_time()</code></a>
and <a class="link" href="glib-Date-and-Time-Functions.html#g-time-val-add" title="g_time_val_add ()"><code class="function">g_time_val_add()</code></a> can be used.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> that is currently locked.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>abs_time</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Date-and-Time-Functions.html#GTimeVal" title="struct GTimeVal"><span class="type">GTimeVal</span></a>, determining the final time.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>cond</code></em> was signalled, or <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> on timeout.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-cond-free"></a><h3>g_cond_free ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_cond_free                         (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a> *cond</code></em>);</pre>
<p>
Destroys the <a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GCond" title="GCond"><span class="type">GCond</span></a>.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="GPrivate"></a><h3>GPrivate</h3>
<pre class="programlisting">typedef struct _GPrivate GPrivate;</pre>
<p>
The <a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="type">GPrivate</span></a> struct is an opaque data structure to represent a
thread private data key. Threads can thereby obtain and set a
pointer which is private to the current thread. Take our
<code class="function">give_me_next_number()</code> example from
above.  Suppose we don't want <code class="literal">current_number</code> to be
shared between the threads, but instead to be private to each thread.
This can be done as follows:
</p>
<p>
</p>
<div class="example">
<a name="id699682"></a><p class="title"><b>Example 9. Using GPrivate for per-thread data</b></p>
<div class="example-contents">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="normal"><a href="glib-Threads.html#GPrivate">GPrivate</a></span><span class="symbol">*</span><span class="normal"> current_number_key </span><span class="symbol">=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span><span class="normal"> </span><span class="comment">/* Must be initialized somewhere</span>
<span class="comment">                                        with g_private_new (g_free); */</span>

<span class="type">int</span>
<span class="function">give_me_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal">  </span><span class="type">int</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Threads.html#g-private-get">g_private_get</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">current_number_key</span><span class="symbol">);</span>

<span class="normal">  </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="normal">current_number</span><span class="symbol">)</span>
<span class="normal">    </span><span class="cbracket">{</span>
<span class="normal">      current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Memory-Allocation.html#g-new">g_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="type">int</span><span class="symbol">,</span><span class="normal"> </span><span class="number">1</span><span class="symbol">);</span>
<span class="normal">      </span><span class="symbol">*</span><span class="normal">current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span>
<span class="normal">      </span><span class="function"><a href="glib-Threads.html#g-private-set">g_private_set</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">current_number_key</span><span class="symbol">,</span><span class="normal"> current_number</span><span class="symbol">);</span>
<span class="normal">    </span><span class="cbracket">}</span>

<span class="normal">  </span><span class="symbol">*</span><span class="normal">current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="function">calc_next_number</span><span class="normal"> </span><span class="symbol">(*</span><span class="normal">current_number</span><span class="symbol">);</span>

<span class="normal">  </span><span class="keyword">return</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">current_number</span><span class="symbol">;</span>
<span class="cbracket">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

</div>
<p><br class="example-break">
</p>
<p>
Here the pointer belonging to the key
<code class="literal">current_number_key</code> is read. If it is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, it has
not been set yet. Then get memory for an integer value, assign this
memory to the pointer and write the pointer back. Now we have an
integer value that is private to the current thread.
</p>
<p>
The <a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="type">GPrivate</span></a> struct should only be accessed via the following
functions.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>All of the <code class="function">g_private_*</code> functions are
actually macros. Apart from taking their addresses, you can however
use them as if they were functions.</p>
</div>
<p>
</p>
</div>
<hr>
<div class="refsect2">
<a name="g-private-new"></a><h3>g_private_new ()</h3>
<pre class="programlisting"><a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="returnvalue">GPrivate</span></a>*           g_private_new                       (<em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> destructor</code></em>);</pre>
<p>
Creates a new <a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="type">GPrivate</span></a>. If <em class="parameter"><code>destructor</code></em> is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, it is a
pointer to a destructor function. Whenever a thread ends and the
corresponding pointer keyed to this instance of <a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="type">GPrivate</span></a> is
non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, the destructor is called with this pointer as the
argument.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p><em class="parameter"><code>destructor</code></em> is used quite differently from <em class="parameter"><code>notify</code></em> in
<a class="link" href="glib-Threads.html#g-static-private-set" title="g_static_private_set ()"><code class="function">g_static_private_set()</code></a>.</p>
</div>
<p>
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>A <a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="type">GPrivate</span></a> can not be freed. Reuse it instead, if you
can, to avoid shortage, or use <a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a>.</p>
</div>
<p>
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>This function will abort if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has not been
called yet.</p>
</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>destructor</code></em> :</span></p></td>
<td>a function to destroy the data keyed to <a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="type">GPrivate</span></a> when
a thread ends.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>a new <a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="type">GPrivate</span></a>.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-private-get"></a><h3>g_private_get ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_private_get                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="type">GPrivate</span></a> *private_key</code></em>);</pre>
<p>
Returns the pointer keyed to <em class="parameter"><code>private_key</code></em> for the current thread. If
<a class="link" href="glib-Threads.html#g-private-set" title="g_private_set ()"><code class="function">g_private_set()</code></a> hasn't been called for the current <em class="parameter"><code>private_key</code></em> and
thread yet, this pointer will be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
</p>
<p>
This function can be used even if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has not yet been
called, and, in that case, will return the value of <em class="parameter"><code>private_key</code></em>
casted to <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a>. Note however, that private data set
<span class="emphasis"><em>before</em></span> <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> will
<span class="emphasis"><em>not</em></span> be retained <span class="emphasis"><em>after</em></span> the
call. Instead, <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> will be returned in all threads directly after
<a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a>, regardless of any <a class="link" href="glib-Threads.html#g-private-set" title="g_private_set ()"><code class="function">g_private_set()</code></a> calls issued
before threading system intialization.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>private_key</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="type">GPrivate</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>the corresponding pointer.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-private-set"></a><h3>g_private_set ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_private_set                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="type">GPrivate</span></a> *private_key</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
<p>
Sets the pointer keyed to <em class="parameter"><code>private_key</code></em> for the current thread.
</p>
<p>
This function can be used even if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has not yet been
called, and, in that case, will set <em class="parameter"><code>private_key</code></em> to <em class="parameter"><code>data</code></em> casted to
<a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="type">GPrivate</span></a>*. See <a class="link" href="glib-Threads.html#g-private-get" title="g_private_get ()"><code class="function">g_private_get()</code></a> for resulting caveats.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>private_key</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="type">GPrivate</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
<td>the new pointer.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="GStaticPrivate"></a><h3>struct GStaticPrivate</h3>
<pre class="programlisting">struct GStaticPrivate {
};
</pre>
<p>
A <a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a> works almost like a <a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="type">GPrivate</span></a>, but it has one
significant advantage. It doesn't need to be created at run-time
like a <a class="link" href="glib-Threads.html#GPrivate" title="GPrivate"><span class="type">GPrivate</span></a>, but can be defined at compile-time. This is
similar to the difference between <a class="link" href="glib-Threads.html#GMutex" title="GMutex"><span class="type">GMutex</span></a> and <a class="link" href="glib-Threads.html#GStaticMutex" title="GStaticMutex"><span class="type">GStaticMutex</span></a>. Now
look at our <code class="function"><code class="function">give_me_next_number()</code></code> example with
<a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a>:
</p>
<p>
</p>
<div class="example">
<a name="id700450"></a><p class="title"><b>Example 10. Using GStaticPrivate for per-thread data</b></p>
<div class="example-contents">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="type">int</span>
<span class="function">give_me_next_number</span><span class="normal"> </span><span class="symbol">()</span>
<span class="cbracket">{</span>
<span class="normal">  </span><span class="keyword">static</span><span class="normal"> </span><span class="usertype">GStaticPrivate</span><span class="normal"> current_number_key </span><span class="symbol">=</span><span class="normal"> <a href="glib-Threads.html#G-STATIC-PRIVATE-INIT:CAPS">G_STATIC_PRIVATE_INIT</a></span><span class="symbol">;</span>
<span class="normal">  </span><span class="type">int</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Threads.html#g-static-private-get">g_static_private_get</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">current_number_key</span><span class="symbol">);</span>

<span class="normal">  </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="normal">current_number</span><span class="symbol">)</span>
<span class="normal">    </span><span class="cbracket">{</span>
<span class="normal">      current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Memory-Allocation.html#g-new">g_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="type">int</span><span class="symbol">,</span><span class="number">1</span><span class="symbol">);</span>
<span class="normal">      </span><span class="symbol">*</span><span class="normal">current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span>
<span class="normal">      </span><span class="function"><a href="glib-Threads.html#g-static-private-set">g_static_private_set</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">current_number_key</span><span class="symbol">,</span><span class="normal"> current_number</span><span class="symbol">,</span><span class="normal"> <a href="glib-Memory-Allocation.html#g-free">g_free</a></span><span class="symbol">);</span>
<span class="normal">    </span><span class="cbracket">}</span>

<span class="normal">  </span><span class="symbol">*</span><span class="normal">current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="function">calc_next_number</span><span class="normal"> </span><span class="symbol">(*</span><span class="normal">current_number</span><span class="symbol">);</span>

<span class="normal">  </span><span class="keyword">return</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">current_number</span><span class="symbol">;</span>
<span class="cbracket">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

</div>
<p><br class="example-break">
</p>
</div>
<hr>
<div class="refsect2">
<a name="G-STATIC-PRIVATE-INIT:CAPS"></a><h3>G_STATIC_PRIVATE_INIT</h3>
<pre class="programlisting">#define G_STATIC_PRIVATE_INIT 
</pre>
<p>
Every <a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a> must be initialized with this macro, before it
can be used.
</p>
<p>
</p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="usertype">GStaticPrivate</span><span class="normal"> my_private </span><span class="symbol">=</span><span class="normal"> <a href="glib-Threads.html#G-STATIC-PRIVATE-INIT:CAPS">G_STATIC_PRIVATE_INIT</a></span><span class="symbol">;</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
</p>
</div>
<hr>
<div class="refsect2">
<a name="g-static-private-init"></a><h3>g_static_private_init ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_private_init               (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a> *private_key</code></em>);</pre>
<p>
Initializes <em class="parameter"><code>private_key</code></em>. Alternatively you can initialize it with
<a class="link" href="glib-Threads.html#G-STATIC-PRIVATE-INIT:CAPS" title="G_STATIC_PRIVATE_INIT"><span class="type">G_STATIC_PRIVATE_INIT</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>private_key</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a> to be initialized.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-private-get"></a><h3>g_static_private_get ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_static_private_get                (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a> *private_key</code></em>);</pre>
<p>
Works like <a class="link" href="glib-Threads.html#g-private-get" title="g_private_get ()"><code class="function">g_private_get()</code></a> only for a <a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a>.
</p>
<p>
This function works even if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has not yet been called.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>private_key</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>the corresponding pointer.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-private-set"></a><h3>g_static_private_set ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_private_set                (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a> *private_key</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> notify</code></em>);</pre>
<p>
Sets the pointer keyed to <em class="parameter"><code>private_key</code></em> for the current thread and
the function <em class="parameter"><code>notify</code></em> to be called with that pointer (<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> or
non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>), whenever the pointer is set again or whenever the
current thread ends.
</p>
<p>
This function works even if <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has not yet been called.
If <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> is called later, the <em class="parameter"><code>data</code></em> keyed to <em class="parameter"><code>private_key</code></em>
will be inherited only by the main thread, i.e. the one that called
<a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a>.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p><em class="parameter"><code>notify</code></em> is used quite differently from <em class="parameter"><code>destructor</code></em> in
<a class="link" href="glib-Threads.html#g-private-new" title="g_private_new ()"><code class="function">g_private_new()</code></a>.</p>
</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>private_key</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
<td>the new pointer.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>notify</code></em> :</span></p></td>
<td>a function to be called with the pointer whenever the
current thread ends or sets this pointer again.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-static-private-free"></a><h3>g_static_private_free ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_static_private_free               (<em class="parameter"><code><a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a> *private_key</code></em>);</pre>
<p>
Releases all resources allocated to <em class="parameter"><code>private_key</code></em>.
</p>
<p>
You don't have to call this functions for a <a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a> with an
unbounded lifetime, i.e. objects declared 'static', but if you have
a <a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a> as a member of a structure and the structure is
freed, you should also free the <a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>private_key</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GStaticPrivate" title="struct GStaticPrivate"><span class="type">GStaticPrivate</span></a> to be freed.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="GOnce"></a><h3>struct GOnce</h3>
<pre class="programlisting">struct GOnce {
  volatile GOnceStatus status;
  volatile gpointer retval;
};
</pre>
<p>
A <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a> struct controls a one-time initialization function. Any
one-time initialization function must have its own unique <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a>
struct.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term">volatile <a class="link" href="glib-Threads.html#GOnceStatus" title="enum GOnceStatus"><span class="type">GOnceStatus</span></a> <em class="structfield"><code><a name="GOnce.status"></a>status</code></em>;</span></p></td>
<td>the status of the <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a>
</td>
</tr>
<tr>
<td><p><span class="term">volatile <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> <em class="structfield"><code><a name="GOnce.retval"></a>retval</code></em>;</span></p></td>
<td>the value returned by the call to the function, if <em class="parameter"><code>status</code></em>
is <a class="link" href="glib-Threads.html#G-ONCE-STATUS-READY:CAPS"><code class="literal">G_ONCE_STATUS_READY</code></a>
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.4</p>
</div>
<hr>
<div class="refsect2">
<a name="GOnceStatus"></a><h3>enum GOnceStatus</h3>
<pre class="programlisting">typedef enum
{
  G_ONCE_STATUS_NOTCALLED,
  G_ONCE_STATUS_PROGRESS,
  G_ONCE_STATUS_READY  
} GOnceStatus;
</pre>
<p>
The possible statuses of a one-time initialization function
controlled by a <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a> struct.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><a name="G-ONCE-STATUS-NOTCALLED:CAPS"></a><span class="term"><code class="literal">G_ONCE_STATUS_NOTCALLED</code></span></p></td>
<td>the function has not been called yet.
</td>
</tr>
<tr>
<td><p><a name="G-ONCE-STATUS-PROGRESS:CAPS"></a><span class="term"><code class="literal">G_ONCE_STATUS_PROGRESS</code></span></p></td>
<td>the function call is currently in progress.
</td>
</tr>
<tr>
<td><p><a name="G-ONCE-STATUS-READY:CAPS"></a><span class="term"><code class="literal">G_ONCE_STATUS_READY</code></span></p></td>
<td>the function has been called.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.4</p>
</div>
<hr>
<div class="refsect2">
<a name="G-ONCE-INIT:CAPS"></a><h3>G_ONCE_INIT</h3>
<pre class="programlisting">#define G_ONCE_INIT { G_ONCE_STATUS_NOTCALLED, NULL }
</pre>
<p>
A <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a> must be initialized with this macro before it can be used.
</p>
<p>
</p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="usertype">GOnce</span><span class="normal"> my_once </span><span class="symbol">=</span><span class="normal"> <a href="glib-Threads.html#G-ONCE-INIT:CAPS">G_ONCE_INIT</a></span><span class="symbol">;</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
</p>
<p class="since">Since 2.4</p>
</div>
<hr>
<div class="refsect2">
<a name="g-once"></a><h3>g_once()</h3>
<pre class="programlisting">#define             g_once(once, func, arg)</pre>
<p>
The first call to this routine by a process with a given <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a>
struct calls <em class="parameter"><code>func</code></em> with the given argument. Thereafter, subsequent
calls to <a class="link" href="glib-Threads.html#g-once" title="g_once()"><code class="function">g_once()</code></a>  with the same <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a> struct do not call <em class="parameter"><code>func</code></em>
again, but return the stored result of the first call. On return
from <a class="link" href="glib-Threads.html#g-once" title="g_once()"><code class="function">g_once()</code></a>, the status of <em class="parameter"><code>once</code></em> will be <a class="link" href="glib-Threads.html#G-ONCE-STATUS-READY:CAPS"><code class="literal">G_ONCE_STATUS_READY</code></a>.
</p>
<p>
For example, a mutex or a thread-specific data key must be created
exactly once. In a threaded environment, calling <a class="link" href="glib-Threads.html#g-once" title="g_once()"><code class="function">g_once()</code></a> ensures
that the initialization is serialized across multiple threads.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Calling <a class="link" href="glib-Threads.html#g-once" title="g_once()"><code class="function">g_once()</code></a> recursively on the same <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a> struct in
<em class="parameter"><code>func</code></em> will lead to a deadlock.</p>
</div>
<p>
</p>
<p>
</p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="normal"><a href="glib-Basic-Types.html#gpointer">gpointer</a></span>
<span class="function">get_debug_flags</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal">  </span><span class="keyword">static</span><span class="normal"> </span><span class="usertype">GOnce</span><span class="normal"> my_once </span><span class="symbol">=</span><span class="normal"> <a href="glib-Threads.html#G-ONCE-INIT:CAPS">G_ONCE_INIT</a></span><span class="symbol">;</span>

<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-once">g_once</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">my_once</span><span class="symbol">,</span><span class="normal"> parse_debug_flags</span><span class="symbol">,</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>

<span class="normal">  </span><span class="keyword">return</span><span class="normal"> my_once</span><span class="symbol">.</span><span class="normal">retval</span><span class="symbol">;</span>
<span class="cbracket">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>once</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a> structure</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
<td>the <a class="link" href="glib-Threads.html#GThreadFunc" title="GThreadFunc ()"><span class="type">GThreadFunc</span></a> function associated to <em class="parameter"><code>once</code></em>. This function
is called only once, regardless of the number of times it and
its associated <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a> struct are passed to <a class="link" href="glib-Threads.html#g-once" title="g_once()"><code class="function">g_once()</code></a>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>arg</code></em> :</span></p></td>
<td>data to be passed to <em class="parameter"><code>func</code></em>
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.4</p>
</div>
<hr>
<div class="refsect2">
<a name="g-once-init-enter"></a><h3>g_once_init_enter ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_once_init_enter                   (<em class="parameter"><code>volatile <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *value_location</code></em>);</pre>
<p>
Function to be called when starting a critical initialization
section. The argument <em class="parameter"><code>value_location</code></em> must point to a static
0-initialized variable that will be set to a value other than 0 at
the end of the initialization section. In combination with
<a class="link" href="glib-Threads.html#g-once-init-leave" title="g_once_init_leave ()"><code class="function">g_once_init_leave()</code></a> and the unique address <em class="parameter"><code>value_location</code></em>, it can
be ensured that an initialization section will be executed only once
during a program's life time, and that concurrent threads are
blocked until initialization completed. To be used in constructs
like this:
</p>
<p>
</p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="usertype">gsize</span><span class="normal"> initialization_value </span><span class="symbol">=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span>

<span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="glib-Threads.html#g-once-init-enter">g_once_init_enter</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">initialization_value</span><span class="symbol">))</span>
<span class="normal">  </span><span class="cbracket">{</span>
<span class="normal">    </span><span class="usertype">gsize</span><span class="normal"> setup_value </span><span class="symbol">=</span><span class="normal"> </span><span class="number">42</span><span class="symbol">;</span><span class="normal"> </span><span class="comment">/* initialization code here */</span>

<span class="normal">    </span><span class="function"><a href="glib-Threads.html#g-once-init-leave">g_once_init_leave</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">initialization_value</span><span class="symbol">,</span><span class="normal"> setup_value</span><span class="symbol">);</span>
<span class="normal">  </span><span class="cbracket">}</span>

<span class="comment">/* use initialization_value here */</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>value_location</code></em> :</span></p></td>
<td>location of a static initializable variable
containing 0.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the initialization section should be entered,
<a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> and blocks otherwise</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.14</p>
</div>
<hr>
<div class="refsect2">
<a name="g-once-init-leave"></a><h3>g_once_init_leave ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_once_init_leave                   (<em class="parameter"><code>volatile <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *value_location</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> initialization_value</code></em>);</pre>
<p>
Counterpart to <a class="link" href="glib-Threads.html#g-once-init-enter" title="g_once_init_enter ()"><code class="function">g_once_init_enter()</code></a>. Expects a location of a static
0-initialized initialization variable, and an initialization value
other than 0. Sets the variable to the initialization value, and
releases concurrent threads blocking in <a class="link" href="glib-Threads.html#g-once-init-enter" title="g_once_init_enter ()"><code class="function">g_once_init_enter()</code></a> on this
initialization variable.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>value_location</code></em> :</span></p></td>
<td>location of a static initializable variable
containing 0.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>initialization_value</code></em> :</span></p></td>
<td>new non-0 value for *<em class="parameter"><code>value_location</code></em>.</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.14</p>
</div>
<hr>
<div class="refsect2">
<a name="g-bit-lock"></a><h3>g_bit_lock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_bit_lock                          (<em class="parameter"><code>volatile <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);</pre>
<p>
Sets the indicated <em class="parameter"><code>lock_bit</code></em> in <em class="parameter"><code>address</code></em>.  If the bit is already
set, this call will block until <a class="link" href="glib-Threads.html#g-bit-unlock" title="g_bit_unlock ()"><code class="function">g_bit_unlock()</code></a> unsets the
corresponding bit.
</p>
<p>
Attempting to lock on two different bits within the same integer is
not supported and will very probably cause deadlocks.
</p>
<p>
The value of the bit that is set is (1u &lt;&lt; <em class="parameter"><code>bit</code></em>).  If <em class="parameter"><code>bit</code></em> is not
between 0 and 31 then the result is undefined.
</p>
<p>
This function accesses <em class="parameter"><code>address</code></em> atomically.  All other accesses to
<em class="parameter"><code>address</code></em> must be atomic in order for this function to work
reliably.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>address</code></em> :</span></p></td>
<td>a pointer to an integer</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>lock_bit</code></em> :</span></p></td>
<td>a bit value between 0 and 31</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.24</p>
</div>
<hr>
<div class="refsect2">
<a name="g-bit-trylock"></a><h3>g_bit_trylock ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_bit_trylock                       (<em class="parameter"><code>volatile <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);</pre>
<p>
Sets the indicated <em class="parameter"><code>lock_bit</code></em> in <em class="parameter"><code>address</code></em>, returning <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if
successful.  If the bit is already set, returns <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> immediately.
</p>
<p>
Attempting to lock on two different bits within the same integer is
not supported.
</p>
<p>
The value of the bit that is set is (1u &lt;&lt; <em class="parameter"><code>bit</code></em>).  If <em class="parameter"><code>bit</code></em> is not
between 0 and 31 then the result is undefined.
</p>
<p>
This function accesses <em class="parameter"><code>address</code></em> atomically.  All other accesses to
<em class="parameter"><code>address</code></em> must be atomic in order for this function to work
reliably.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>address</code></em> :</span></p></td>
<td>a pointer to an integer</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>lock_bit</code></em> :</span></p></td>
<td>a bit value between 0 and 31</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the lock was acquired</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.24</p>
</div>
<hr>
<div class="refsect2">
<a name="g-bit-unlock"></a><h3>g_bit_unlock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_bit_unlock                        (<em class="parameter"><code>volatile <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);</pre>
<p>
Clears the indicated <em class="parameter"><code>lock_bit</code></em> in <em class="parameter"><code>address</code></em>.  If another thread is
currently blocked in <a class="link" href="glib-Threads.html#g-bit-lock" title="g_bit_lock ()"><code class="function">g_bit_lock()</code></a> on this same bit then it will be
woken up.
</p>
<p>
This function accesses <em class="parameter"><code>address</code></em> atomically.  All other accesses to
<em class="parameter"><code>address</code></em> must be atomic in order for this function to work
reliably.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>address</code></em> :</span></p></td>
<td>a pointer to an integer</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>lock_bit</code></em> :</span></p></td>
<td>a bit value between 0 and 31</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.24</p>
</div>
</div>
<div class="refsect1">
<a name="glib-Threads.see-also"></a><h2>See Also</h2>
<a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a>, <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
</div>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.17</div>
</body>
</html>